Migrating from CloudBees Jenkins Enterprise 1.x to CloudBees Core on modern cloud platforms

This migration guide provides instructions on how to migrate your entire CloudBees Jenkins Enterprise 1.x installation over to a new CloudBees Core on modern cloud platforms installation.

Prerequisites

  • On your CloudBees Jenkins Enterprise 1.x installation’s Operations Center, ensure you have made a note of (and can easily access) all credentials configured globally and for credentials scoped to folders.

  • For each CloudBees Jenkins Enterprise master (that is, each Managed Master, Team Master and Client Master configured on your existing CloudBees Jenkins Enterprise 1.x installation):

    • Streamline your CloudBees Jenkins Enterprise masters by identify plugins which are no longer being used and uninstall them. This can be achieved by installing/using the Plugin Usage Plugin.

    • ( Optional ) If you need to do so, (re-)organize any current projects and jobs (including those in subfolders) into folders based on distinct criteria, such as specific lines of business or teams within your organization.

  • ( Optional ) Plugins on CloudBees Jenkins Enterprise 1.x can be installed to CloudBees Core either manually or automatically. To install these plugins automatically, install the jq command line tool on a machine with access to this new CloudBees Core Operations Center.

Install CloudBees Core on modern cloud platforms

This migration process requires you to start with a clean CloudBees Core on modern cloud platforms installation on appropriate Kubernetes infrastructure.

  1. Install CloudBees Core on modern cloud platforms with all the Managed Masters, Team Masters and Client Masters (connected to your CloudBees Core on modern cloud platforms instance) which you had previously set up and configured on CloudBees Jenkins Enterprise 1.x.

  2. On your new CloudBees Core installation’s Operations Center, recreate any folders you had previously configured on CloudBees Jenkins Enterprise 1.x.

  3. On the Operations Center and masters of your new CloudBees Core installation, create Kubernetes shared pod templates and pod templates, respectively, which are equivalent to any agent templates you had previously configured on CloudBees Jenkins Enterprise 1.x.
    When creating your Kubernetes pod templates, complete as many fields as possible - especially details that match those defined in the equivalent agent templates on CloudBees Jenkins Enterprise 1.x. Refer to the table below for details on these matching fields.

Migrate key Operations Center data

This section of the migration guide covers all migration aspects of Operations Center from your CloudBees Jenkins Enterprise 1.x instance over to your CloudBees Core instance.

The Operations Center migration process must be conducted first before the masters can be migrated.

Migrate credentials

To migrate credentials from CloudBees Jenkins Enterprise 1.x to CloudBees Core:

  1. Set up the Jenkins CLI tool for each Operations Center of your CloudBees Jenkins Enterprise 1.x and new CloudBees Core instances.

  2. Export credentials on your CloudBees Jenkins Enterprise 1.x Operations Center, in XML format, using the appropriate command/s:

    • For credentials scoped globally, use this command (specifying your actual cje-1-x-url value and port-number if necessary):

      $ java -jar jenkins-cli.jar -s https://cje-1-x-url:port-number/cjoc/ list-credentials-as-xml system::system::jenkins > credentials.xml
    • If you have credentials scoped to a given folder, use this command:

      $ java -jar jenkins-cli.jar -s https://cje-1-x-url:port-number/cjoc/ list-credentials-as-xml folder::item::/full/name/of/folder > credentials-folder-name.xml
      Note
      Run this command for every folder to which credentials have been scoped.
  3. Since credentials are exported to these XML files with redacted secrets (to maintain their secrecy and security), locate each instance of <secret-redacted/> throughout all the credentials.xml and/or credentials-folder-name.xml files you exported and replace them with their correct secret values.

  4. Import credentials to your new CloudBees Core Operations Center, using the appropriate command/s:

    • For credentials scoped globally, use this command (specifying your actual cloudbees-core-url value and port-number if necessary):

      $ java -jar jenkins-cli.jar -s https://cloudbees-core-url:port-number/cjoc/ import-credentials-as-xml system::system::jenkins < credentials.xml
    • If you had credentials scoped to a given folder in CloudBees Jenkins Enterprise 1.x, use this command for the equivalent folder in CloudBees Core:

      $ java -jar jenkins-cli.jar -s https://cloudbees-core-url:port-number/cjoc/ import-credentials-as-xml folder::item::/full/name/of/folder < credentials-folder-name.xml
      Note
      Run this command for every equivalent folder (in your CloudBees Core Operations Center) to which credentials were scoped on your CloudBees Jenkins Enterprise 1.x Operations Center.

Ensure plugins are harmonized

To harmonize plugins between CloudBees Jenkins Enterprise 1.x and CloudBees Core, ensure that the Operations Center of your new CloudBees Core installation has the same plugins that were installed on the Operations Center of the CloudBees Jenkins Enterprise 1.x installation.

  1. Ensure you are still set up to use the Jenkins CLI tool for each Operations Center of your CloudBees Jenkins Enterprise 1.x and new CloudBees Core instances.

  2. Export the list of plugins on your CloudBees Jenkins Enterprise 1.x Operations Center, in JSON format, using this command (specifying your actual cje-1-x-url value and port-number if necessary):

    $ java -jar jenkins-cli.jar -s https://cje-1-x-url:port-number/cjoc/ list-plugins-v2 --output json > plugins.json
  3. On your new CloudBees Core Operations Center, install these plugins either manually or automatically via a command:

    • To install these plugins manually:

      1. Run the same command you did on CloudBees Jenkins Enterprise 1.x (in the previous step) but on your new CloudBees Core instance instead (specifying your own cloudbees-core-url value and port-number if necessary):

        $ java -jar jenkins-cli.jar -s https://cloudbees-core-url:port-number/cjoc/ list-plugins-v2 --output json > plugins-cloud-core.json
      2. Compare the outputs of the plugins.json and plugins-cloud-core.json files, and manually install the required missing plugins on your new CloudBees Core Operations Center.

    • To install these plugins automatically via a command:

      1. Ensure you have installed the jq command line tool (mentioned in the prerequisites above).

      2. Force the installation of all plugins installed on the CloudBees Jenkins Enterprise 1.x Operations Center (listed in plugins.json), on the new CloudBees Core Operations Center, with this command:

        $ for plugin in $(cat plugins.json | jq -r .data[].id); do java -jar jenkins-cli.jar -noKeyAuth -s https://cloudbees-core-url:port-number/cjoc/ install-plugin ${plugin}; done

Convert agent templates to Kubernetes (shared) pod templates

This is a complex process, which involves the following stages:

Export agent template definitions from CloudBees Jenkins Enterprise 1.x Operations Center and masters

  1. Ensure you are still set up to use the Jenkins CLI tool for the Operations Center and masters of your CloudBees Jenkins Enterprise 1.x instance.

  2. Export the definitions for all agent templates on your CloudBees Jenkins Enterprise 1.x Operations Center using the following command (specifying your actual cje-1-x-url value and port-number if necessary):

    $ java -jar jenkins-cli.jar -s https://cje-1-x-url:port-number/cjoc/ agent-template > agent-templates.json
  3. Export the definitions for all agent templates on your CloudBees Jenkins Enterprise 1.x masters using the following command (specifying your actual cje-1-x-url and master-name values, and port-number if necessary):

    $ java -jar jenkins-cli.jar -s https://cje-1-x-url:port-number/master-name/ agent-template > agent-templates-master-name.json
    Note
    Run this command for every master (that is, Managed Masters and Team Masters) on which agent templates have been defined.
    Example of an exported agent template definition file, showing a single agent template definition and all possible properties with sample values.
    {
        "data": [
            {
                "atm": {
                    "constraints": [],
                    "containerProperties": [
                        {
                            "key": "volumes-from",
                            "type": "ParameterSpec",
                            "value": "certs"
                        },
                        {
                            "name": "...",
                            "type": "EnvironmentVariableContainerProperty",
                            "value": "..."
                        },
                        {
                            "containerPath": "...",
                            "hostPath": "...",
                            "readOnly": true/false,
                            "type": "VolumeSpec",
                            "volumeType": {
                                "hostPath": "...",
                                "type": "BindMount/Volume"
                            }
                        },
                        {
                            "executable": true/false,
                            "extract": true/false,
                            "type": "URISpec",
                            "value": "uri-value"
                        },
                        {
                            "forcePull": true/false,
                            "type": "ForcePullContainerProperty"
                        },
                        {
                            "privilegeMode": true/false,
                            "type": "PrivilegedModeContainerProperty"
                        },
                        {
                            "containerPort": port-number,
                            "hostPort": port-number,
                            "protocol": "TCP/UDP",
                            "type": "PortMappingSpec"
                        },
                        {
                            "type": "CustomDockerShellProperty",
                            "value": "/bin/sh -c"
                        }
                    ],
                    "cpus": 0.1,
                    "displayName": "...",
                    "image": ".../...",
                    "jnlpArgs": "",
                    "jvmArgs": "...",
                    "jvmMemory": 1024,
                    "labelString": null,
                    "memory": 2048,
                    "name": "...",
                    "remoteFS": "..."
                }
            }
        ],
        "version": "1"
    }

Export Kubernetes (shared) pod template definitions from CloudBees Core Operations Center and masters

  1. Ensure you are still set up to use the Jenkins CLI tool for the Operations Center and masters of your new CloudBees Core instance.

  2. Export the definitions for all recreated Kubernetes shared pod templates on your CloudBees Core Operations Center (that is, defined within a Kubernetes cloud configuration) using the following command (specifying your actual cloudbees-core-url value and port-number if necessary):

    $ java -jar jenkins-cli.jar -s https://cloudbees-core-url:port-number/cjoc/ shared-pod-template > shared-pod-templates.json
  3. Export the definitions for all recreated Kubernetes pod templates on your CloudBees Core masters using the following command (specifying your actual cloudbees-core-url and master-name values, and port-number if necessary):

    $ java -jar jenkins-cli.jar -s https://cloudbees-core-url:port-number/master-name/ pod-template > pod-templates-master-name.json
    Note
    Run this command for every master (that is, Managed Masters and Team Masters) on which Kubernetes pod templates have been defined.
    Example of an exported Kubernetes (shared) pod template definition file.
    {
        "data": [
            {
                "podTemplate": {
                    "label": "documentation",
                    "name": "documentation-packging",
                    "displayName": "Kubernetes Pod Template",
                    "activeDeadlineSeconds": 44,
                    "alwaysPullImage": false,
                    "customWorkspaceVolumeEnabled": true,
                    "args": "cat",
                    "capOnlyOnAlivePods": true,
                    "command": "/bin/sh -c",
                    "idleMinutes": 1,
                    "inheritFrom": "abc",
                    "instanceCap": 2,
                    "namespace": "doc-group",
                    "nodeSelector": "77",
                    "nodeUsageMode": "NORMAL",
                    "privileged": false,
                    "resourceLimitCpu": "1",
                    "resourceLimitMemory": "1024",
                    "resourceRequestCpu": "1",
                    "resourceRequestMemory": "1024",
                    "serviceAccount": "88",
                    "slaveConnectTimeout": 99,
                    "annotations": [
                        {
                            "key": "var3",
                            "value": "44"
                        }
                    ],
                    "containers": [
                        {
                            "alwaysPullImage": false,
                            "args": "cat",
                            "command": "/bin/sh -c",
                            "envVars": [
                                {
                                    "type": "KeyValueEnvVar",
                                    "key": "env",
                                    "value": "22"
                                },
                                {
                                    "type": "SecretEnvVar",
                                    "key": "secret_env",
                                    "secretKey": "YeahYeah",
                                    "secretName": "abc.corp.com"
                                }
                            ],
                            "image": "java",
                            "livenessProbe": {
                                "execArgs": "inode",
                                "failureThreshold": 16,
                                "initialDelaySeconds": 10,
                                "periodSeconds": 17,
                                "successThreshold": 0,
                                "timeoutSeconds": 15
                            },
                            "name": "java",
                            "ports": [
                                {
                                    "containerPort": 6789,
                                    "hostPort": 9876,
                                    "name": "port6789"
                                }
                            ],
                            "privileged": false,
                            "resourceLimitCpu": "1",
                            "resourceLimitMemory": "1024",
                            "resourceRequestCpu": "1",
                            "resourceRequestMemory": "1024",
                            "shell": null,
                            "ttyEnabled": true,
                            "workingDir": "/home/jenkins"
                        }
                    ],
                    "envVars": [
                        {
                            "key": "VAR1",
                            "type": "KeyValueEnvVar",
                            "value": "42"
                        },
                        {
                            "key": "VAR2",
                            "secretKey": "",
                            "secretName": "derek-secret",
                            "type": "SecretEnvVar"
                        }
                    ],
                    "imagePullSecrets": [
                        {
                            "name": "abc.corp.com"
                        }
                    ],
                    "volume": {
                        "memory": true,
                        "type": "EmptyDirWorkspaceVolume"
                    },
                    "volumes": [
                        {
                            "hostPath": "/extra/workspace",
                            "mountPath": "/workspace",
                            "type": "HostPathVolume"
                        }
                    ],
                    "yaml": ""
                }
            }
        ],
        "version": "1"
    }

Ensure your Kubernetes (shared) pod template definitions match their equivalent agent template definitions

If necessary, modify your shared-pod-templates.json and pod-templates-master-name.json files with the correct details from their equivalent/respective agent-templates.json and agent-templates-master-name.json files.

CloudBees Jenkins Enterprise 1.x
agent template
CloudBees Core
Kubernetes (shared) pod template

UI

JSON

UI

JSON

Notes

Display Name

name

Name

name

To ensure any instances of node('agent-name') blocks in Scripted Pipelines continue to function, the name values of your Kubernetes (shared) pod templates and their equivalent agent templates (from CloudBees Jenkins Enterprise 1.x) must match.

Furthermore, the Kubernetes (shared) pod template’s first container template’s name must be jnlp.

displayName

displayName

Use when no label is specified

N/A

N/A

N/A

Configure the Defaults Provider Template Name value of the Kubernetes shared cloud configuration (not a Kubernetes pod template definition) to have the same name value of the agent template from CloudBees Jenkins Enterprise 1.x.

Enable this agent template

N/A

N/A

N/A

No equivalent on CloudBees Core.

CPU Shares

cpus

Containers  Container Template  Advanced  Request CPU
and
Limit CPU

resourceRequestCpu
and
resourceLimitCpu, respectively

In the Kubernetes (shared) pod template definition, specify both of these values in the container template as 1.

Memory (MB)

memory

Containers  Container Template  Advanced  Request Memory
and
Limit Memory

resourceRequestMemory
and
resourceLimitMemory, respectively

In the Kubernetes (shared) pod template definition, make these values the same as memory in the CloudBees Jenkins Enterprise 1.x agent template definition.

Note that Kubernetes supports numerous methods for specifying memory. The unit "M" in Kubernetes, indicates the decimal mega (e.g., 10002), whereas the unit "Mi", indicates mibi (e.g., 10242). Mesos' "MB/GB" units map to Kubernetes' "Mi/Gi" units, respectively.

JVM Memory (MB)

jvmMemory

Containers  Container Template  EnvVars  Key
and
Value

"envVars": [
{
"type": "KeyValueEnvVar"
"key": "JAVA_OPTS"
"value": "…​"
}, …​
], …​

In the Kubernetes (shared) pod template definition, make the value of value (e.g. using the -Xmx option) the same as jvmMemory in the CloudBees Jenkins Enterprise 1.x agent template definition.

JVM Arguments

jvmArgs

Containers  Container Template  EnvVars  Key
and
Value

"envVars": [
{
"type": "KeyValueEnvVar"
"key": "JAVA_OPTS"
"value": "…​"
}, …​
], …​

In the Kubernetes (shared) pod template definition, make the value of value the same as jvmArgs in the CloudBees Jenkins Enterprise 1.x agent template definition.

If you specified the JVM Memory (MB)/jvmMemory value in the CloudBees Jenkins Enterprise 1.x agent template definition, incorporate this value into this single JAVA_OPTS value with the -Xmx option.

JNLP Arguments

jnlpArgs

Containers  Container Template  EnvVars  Key
and
Value

"envVars": [
{
"type": "KeyValueEnvVar"
"key": "JAVA_OPTS"
"value": "…​"
}, …​
], …​

In the Kubernetes (shared) pod template definition, make the value of value the same as jnlpArgs in the CloudBees Jenkins Enterprise 1.x agent template definition.

If you specified the JVM Memory (MB)/jvmMemory and/or JVM Arguments/jvmArgs value in the CloudBees Jenkins Enterprise 1.x agent template definition, incorporate this value into this single JAVA_OPTS value.

Remote root directory

remoteFS

Containers  Container Template  Working directory

workingDir

In the Kubernetes (shared) pod template definition, make this value the same as it was in the CloudBees Jenkins Enterprise 1.x agent template definition.

Image

image

Containers  Container Template  Docker image

image

In the Kubernetes (shared) pod template definition, make this value the same as remoteFS in the CloudBees Jenkins Enterprise 1.x agent template definition.

Also, the Kubernetes (shared) pod template’s first container template’s name must be jnlp.

Options  Force Pull Image

forcePull

Containers  Container Template  Always pull image

"containers": [
{
"alwaysPullImage": …​,
}, …​
], …​

In the Kubernetes (shared) pod template definition, make this value the same as forcePull in the CloudBees Jenkins Enterprise 1.x agent template definition.

Options  Additional URI  Value,
Executable
and
Extract

"containerProperties": [ …​
{
"type": "URISpec",
"value": "uri-value"
"executable": …​,
"extract": …​,
}, …​
], …​

N/A

N/A

No equivalent on CloudBees Core.

If you want to specify the URL for a private registry containing relevant images, read more about configuring secrets for a Kubernetes environment in the relevant Kubernetes documentation, and add specify the Kubernetes pod template’s ImagePullSecrets  Name value.

"imagePullSecrets": [
{
"name": "uri-value"
}
], …​

Options  Environment Variable  Name
and
Value

"containerProperties": [ …​
{
"type": "EnvironmentVariable\
ContainerProperty",
"name": "…​"
"value": …​,
}, …​
], …​

Containers  Container Template  EnvVars  Key
and
Value,
or
Key,
SecretName
and
SecretKey

"envVars": [
{
"type": "KeyValueEnvVar"
"key": "JAVA_OPTS"
"value": "…​"
}, …​
], …​
or
"envVars": [
{
"type": "SecretEnvVar",
"key": "…​",
"secretKey": "..",
"secretName": "…​"
}, …​
], …​

In the Kubernetes (shared) pod template definition, use the equivalent values utilized in the CloudBees Jenkins Enterprise 1.x agent template definition.

Options  Launch in privileged mode

privileged

Containers  Container Template  Advanced  Run in privileged mode

"containers": [
{ …​
"privileged": …​,
}, …​
], …​

In the Kubernetes (shared) pod template definition, make this value the same as privileged in the CloudBees Jenkins Enterprise 1.x agent template definition.

Options  Parameter  Key
and
Value

"containerProperties": [ …​
{
"type": "ParameterSpec",
"key": "…​",
"value": "…​"
}, …​
], …​

N/A

N/A

No equivalent on CloudBees Core.

It is not possible to supply additional parameters when launching Docker in a Kubernetes environment.

Options  Port Mapping  Host Port,
Container Port
and
Protocol

"containerProperties": [ …​
{
"type": "PortMappingSpec"
"hostPort": …​,
"containerPort": …​,
"protocol": "TCP/UDP",
}, …​
], …​

Containers  Container Template  Advanced  PortMappings  Name,
ContainerPort
and
HostPort

"ports": [ …​
{
"name": "…​"
"containerPort": …​,
"hostPort": …​,
}, …​
], …​

In the Kubernetes (shared) pod template definition, use the equivalent values utilized in the CloudBees Jenkins Enterprise 1.x agent template definition.

Note that each port mapping configuration in your CloudBees Core Kubernetes (shared) pod template definitions can be named.

Options  Use custom docker shell command  Custom shell command

"containerProperties": [ …​
{
"type": "CustomDockerShellProperty",
"value": "…​"
}, …​
], …​

Containers  Container Template  Command to run

command

In the Kubernetes (shared) pod template definition, make this value the same as this Custom shell command/value field in the CloudBees Jenkins Enterprise 1.x agent template definition.

Options  User  Docker user

N/A

N/A

N/A

No equivalent on CloudBees Core.

It is not possible to specify a User ID with which to run a container in a Kubernetes environment.

Options  Volume  Volume Type,
Host Path,
Container Path,
and Read-only

"containerProperties": [ …​
{
"type": "VolumeSpec",
"volumeType": {
"hostPath": "…​",
"type": "BindMount/Volume"
},
"containerPath": "…​",
"hostPath": "…​",
"readOnly": …​
}, …​
], …​

Volumes  Host Path Volume  Host path
and
Mount path

"volumes": [ …​
{
"type": "HostPathVolume"
"hostPath": "…​",
"mountPath": "…​",
}, …​
], …​

In the Kubernetes (shared) pod template definition, use the equivalent values utilized in the CloudBees Jenkins Enterprise 1.x agent template definition.

Import your updated Kubernetes (shared) pod template definitions to CloudBees Core Operations Center and masters

  1. Ensure you are still set up to use the Jenkins CLI tool for the Operations Center and masters of your new CloudBees Core instance.

  2. Import the updated definitions for all recreated Kubernetes shared pod templates on your CloudBees Core Operations Center (that is, defined within a Kubernetes cloud configuration) using the following command (specifying your actual cloudbees-core-url value and port-number if necessary):

    $ java -jar jenkins-cli.jar -s https://cloudbees-core-url:port-number/cjoc/ shared-pod-template --update < shared-pod-templates.json
  3. Import the updated definitions for all recreated Kubernetes pod templates on your CloudBees Core masters using the following command (specifying your actual cloudbees-core-url and master-name values, and port-number if necessary):

    $ java -jar jenkins-cli.jar -s https://cloudbees-core-url:port-number/master-name/ pod-template --update < pod-templates-master-name.json
    Note
    Run this command for every master (that is, Managed Masters and Team Masters) on which Kubernetes pod templates have been defined.

Migrate masters

Migrating masters (Managed Masters and Team Masters) from CloudBees Jenkins Enterprise 1.x to your new CloudBees Core installation involves backing up your masters on your CloudBees Jenkins Enterprise 1.x installation and restoring them to the new masters you created as part of setting up your new CloudBees Core installation.

  1. Ensure you are still set up to use the Jenkins CLI tool for the masters of your CloudBees Jenkins Enterprise 1.x installation and new CloudBees Core installation.

  2. On your CloudBees Jenkins Enterprise 1.x installation back up each master.

    • Do this through the New Item  Backup and Restore (project)  Build  Take backup on your CJE 1.x master.

    • When configuring the Take Backup section of this project, select What to back up?  System configuration and specify the following items in the Excludes list:

      • monitoring/

      • caches/

      • operations-center-cloud*

      • operations-center-client*

      • plugins/operations-center-analytics-config*

      • plugins/operations-center-analytics-config/

      • plugins/operations-center-analytics-reporter*

      • plugins/operations-center-analytics-reporter/

      • plugins/palace-cloud*

      • plugins/palace-cloud/

      • plugins/tiger-tenant*

      • plugins/tiger-tenant/

  3. On your new CloudBees Core installation, for each respective new master, restore each master from the backup taken from CloudBees Jenkins Enterprise 1.x.