Migrating CloudBees Jenkins Platform to CloudBees CI

12 minute read

This guide explains how to migrate your CloudBees Jenkins Platform client controller and operations center instance to CloudBees CI on traditional platforms. Read Determining the best migration and upgrade path for your team before attempting the migration steps.

End-of-life announcement

The CloudBees Jenkins Platform (CJP) product which has been available since November 16, 2016, is reaching the end of its product lifecycle. CloudBees will declare this product end-of-life (EOL) on June 30, 2023.

Please note that once EOL is reached, CloudBees will no longer provide commercial support for this product. Please contact CloudBees Support if you have any concerns or questions.

Video walk-through of this guide

Before beginning the migration process, you can watch this overview of the migration process.

Migrating CloudBees Jenkins Platform to CloudBees CI

Determining the best migration and upgrade path for your team

Many customers have questions about upgrading and migration, and are unsure which should be completed first. This section provides general guidance that should be applicable to all customers, but in unique situations please reach out to CloudBees Support for additional guidance.

Each of these steps should be reviewed to determine if they are applicable to your team.

CloudBees recommends that you test each individual step in a test cluster, apply that individual step to your production environment, and then move onto the next step. This path takes more time due to the multiple testing phases that are required, but makes it easier to isolate the root cause of any unexpected issues, since the number of changes happening at once are reduced, and it is easier to remember the commands and steps you followed for that individual change.

Another option is to first test all steps sequentially in a test cluster. Once you are confident that the test cluster is working as expected, you can take a production backup, and then apply the same steps sequentially in your production environment. However, this is more risky if you did not maintain accurate notes of how you performed each of the steps and the exact commands that you ran to apply the changes. This option is more likely to encounter unexpected failures due to human error.

  1. Take a full backup of your $JENKINS_HOME directory from your CloudBees Jenkins Platform client controller or operations center instance by following the Backup and restore documentation. If using the -Djenkins.model.Jenkins.buildsDir=BUILDS_DIR startup argument, then save a copy of this directory as well. This ensures that you can restore service if there are critical issues encountered that CloudBees Support cannot quickly resolve.

  2. Determine if you are going to migrate to new hardware or a new OS version at the same time as migrating the CloudBees software.

    • If you choose to migrate to new hardware or a new OS at the same time, it makes troubleshooting the root cause of an issue more difficult, and requires more involvement from your Linux system administrators and network administrators during the migration if there are problems (for example, if a network firewall needs to be reconfigured).

    • There are some scenarios where an OS upgrade is required. For example, if you are running an OS that does not have systemd, you must migrate to a newer OS version before performing the upgrade and migration of CloudBees software.

    • For more information, refer to Advanced topic: Migrating to new machines at the same time as migrating CloudBees Jenkins Platform to CloudBees CI.

  3. If you are running CloudBees Jenkins Platform 2.332.1.5 or earlier, these versions are no longer supported. CloudBees recommends that you upgrade to CloudBees Jenkins Platform 2.346.4.1 and then migrate to CloudBees CI.

    When the upgrade is complete, you will be running a CloudBees Jenkins Platform version that supports both Java 8 and Java 11 when performing the migration to CloudBees CI.

    • CloudBees recommends that you open an Assisted Update ticket with CloudBees Support to get a custom upgrade plan for your environment. The assisted update process covers the upgrade steps, this document covers the migration steps, and during the consultation meeting with CloudBees Support, you can ask questions about the upgrade as well as the migration. For more information on upgrading CloudBees Jenkins Platform, refer to Upgrading CloudBees Jenkins Platform.

    • You can upgrade one year at a time, so many customers that run out of supported versions have to do multiple upgrades, regardless. For more information, refer to Upgrading between versions.

  4. Migrate your CloudBees Jenkins Platform controller to CloudBees CI at the equivalent version. For example, if you are currently running CloudBees Jenkins Platform 2.346.4.1, you should migrate to CloudBees CI on traditional platforms 2.346.4.1.

    If you are on a CloudBees Jenkins Platform fixed release, migrate to the CloudBees CI version that was released on the day of your fixed line release or to a more recent version. You can only upgrade one year at a time. For more information, refer to Upgrading between versions.

    The next decision for this step is to determine which CloudBees Jenkins Platform user account you should use.

  5. Now that you have migrated to a currently supported CloudBees CI version which supports Java 11, you must upgrade from Java 8 to 11. For more information, refer to Migrate to Java 11.

  6. Once you are running a supported CloudBees CI version using Java 11, you can upgrade to newer CloudBees CI versions.

Deciding which CloudBees Jenkins Platform user account to use

There are many ways to migrate between CloudBees Jenkins Platform to CloudBees CI, this section will cover the two recommended paths when using RPM or DEB based Linux installations.

To understand why there are two paths, it’s important to know that CloudBees Jenkins Platform by default runs as the Linux user jenkins (for the client controller) and jenkins-oc (for the operations center), and CloudBees CI by default runs as the Linux user cloudbees-core-cm (for the client controller) and cloudbees-core-oc (for the operations center).

  • Option A is to adopt the new Linux user account that runs CloudBees CI and a new $JENKINS_HOME directory.

    • This has the benefit that you don’t need to modify the JENKINS_USER setting, and since you are making a copy of your $JENKINS_HOME directory, your original data is retained until you choose to delete it.

    • The drawback is that you have to copy and then chown your entire $JENKINS_HOME directory, which for some customers with large installations can take a very long amount of time for the cp and chown command to run, which can greatly increase the time required to migrate.

    • The steps for this option are: Option A: Migrating using the new default user account and new $JENKINS_HOME directory.

  • Option B is to keep the same Linux user account that you are already using (jenkins and jenkins-oc, or your chosen user account) and the same $JENKINS_HOME directory.

    • This option is the recommended path if running a chown on your $JENKINS_HOME directory will take a longer amount of time than you are comfortable with during the migration maintenance window. For example, if you have a large number of files in your $JENKINS_HOME directory, or if you use storage that is not SSD.

    • May be required if you have corporate policies regarding which user accounts are allowed to run services.

    • The steps for this option are: Option B: Migrating using the existing user account and $JENKINS_HOME directory.

Option A: Migrating using the new default user account and new $JENKINS_HOME directory

Migrating using the new default user account and new $JENKINS_HOME directory

Watch the video

This video provides a step-by-step for migrating from CloudBees Jenkins Platform to CloudBees CI using the new default user account.

Watch the video

To migrate using the new default user account and new $JENKINS_HOME directory, you must:

  1. Migrate an operations center instance from CloudBees Jenkins Platform to CloudBees CI using the new default user account and new $JENKINS_HOME directory.

  2. Migrate a client controller instance from CloudBees Jenkins Platform to CloudBees CI using the new default user account and new $JENKINS_HOME directory.

Option A: Migrating an operations center instance from CloudBees Jenkins Platform to CloudBees CI using the new default user account and new $JENKINS_HOME directory

Follow these steps to migrate an operations center instance from CloudBees Jenkins Platform to CloudBees CI:

  1. Stop and disable your CloudBees Jenkins Platform operations center instance:

    sudo service jenkins-oc stop
sudo systemctl disable jenkins-oc
    ▼

  2. Install the operations center for CloudBees CI on traditional platforms.

  3. Stop your CloudBees CI operations center instance.

    sudo service cloudbees-core-oc stop
    ▼

  4. From your old CloudBees Jenkins Platform operations center installation, create a copy of the $JENKINS_HOME directory (named jenkins-oc) for CloudBees CI (named cloudbees-core-oc) and change the ownership of this new directory to the new cloudbees-core-oc user:

    cd /var/lib/
sudo cp -rf jenkins-oc/* cloudbees-core-oc/
cd cloudbees-core-oc/
sudo chown -R cloudbees-core-oc:cloudbees-core-oc .
    ▼

  5. Migrate service options such as JENKINS_JAVA_OPTIONS from /etc/sysconfig/jenkins-oc to /etc/sysconfig/cloudbees-core-oc (or /etc/default/jenkins-oc to /etc/default/cloudbees-core-oc), per How to add Java arguments to Jenkins.

    Confirm the differences by running:

    diff /etc/sysconfig/jenkins-oc /etc/sysconfig/cloudbees-core-oc
# or
diff /etc/default/jenkins-oc /etc/default/cloudbees-core-oc
    ▼

  6. Start your new CloudBees CI operations center instance.

    sudo service cloudbees-core-oc start
    ▼

  7. Uninstall the CloudBees Jenkins Platform operations center:

    • On Ubuntu or Debian:

      sudo apt-get purge jenkins-oc
      ▼

    • On Red Hat, CentOS, Fedora or Amazon Linux 2:

      sudo yum remove jenkins-oc
      ▼

    • On OpenSUSE:

      sudo zypper remove jenkins-oc
      ▼

  8. (Optional) If the migration of your operations center instance to CloudBees CI ran successfully, you can remove the old CloudBees Jenkins Platform operations center directory:

    rm -rf /var/lib/jenkins-oc
    ▼

Option A: Migrating a client controller instance from CloudBees Jenkins Platform to CloudBees CI using the new default user account and new $JENKINS_HOME directory

Follow these steps to migrate a client controller instance from CloudBees Jenkins Platform to CloudBees CI.

  1. Stop and disable your CloudBees Jenkins Platform client controller instance:

    sudo service jenkins stop
sudo systemctl disable jenkins
    ▼

  2. Install the client controller for CloudBees CI on traditional platforms.

  3. Stop your CloudBees CI client controller instance:

    sudo service cloudbees-core-cm stop
    ▼

  4. From your old CloudBees Jenkins Platform operations center installation, create a copy of the $JENKINS_HOME directory (named jenkins) for CloudBees CI (named cloudbees-core-cm) and change the ownership of this new directory to the new cloudbees-core-cm user:

    cd /var/lib/
sudo cp -rf jenkins/* cloudbees-core-cm/
cd cloudbees-core-cm/
sudo chown -R cloudbees-core-cm:cloudbees-core-cm .
    ▼

  5. Migrate service options such as JENKINS_JAVA_OPTIONS from /etc/sysconfig/jenkins to /etc/sysconfig/cloudbees-core-cm (or /etc/default/jenkins to /etc/default/cloudbees-core-cm), per How to add Java arguments to Jenkins.

    Confirm the differences by running:

    diff /etc/sysconfig/jenkins /etc/sysconfig/cloudbees-core-cm
# or
diff /etc/default/jenkins /etc/default/cloudbees-core-cm
    ▼

  6. Start your new CloudBees CI client controller instance.

    sudo service cloudbees-core-cm start
    ▼

  7. Uninstall the CloudBees Jenkins Platform client controller:

    • On Ubuntu or Debian.

      sudo apt-get purge jenkins
      ▼

    • On Red Hat, CentOS, Fedora or Amazon Linux 2.

      sudo yum remove jenkins
      ▼

    • On OpenSUSE.

      sudo zypper remove jenkins
      ▼

  8. (Optional) If the migration of your client controller instance to CloudBees CI ran successfully, you can remove the old CloudBees Jenkins Platform client controller directory:

    rm -rf /var/lib/jenkins
    ▼

Option B: Migrating using the existing user account and $JENKINS_HOME directory

Migrating using the existing user account and $JENKINS_HOME directory

Watch the video

This video provides a step-by-step guide for migrating the existing user account and $JENKINS_HOME directory.

Watch the video

To migrate using the existing user account and $JENKINS_HOME directory, you must:

  1. Migrate an operations center instance from CloudBees Jenkins Platform to CloudBees CI using the existing user account and $JENKINS_HOME directory.

  2. Migrate a client controller instance from CloudBees Jenkins Platform to CloudBees CI using the existing user account and $JENKINS_HOME directory.

Option B: Migrating an operations center instance from CloudBees Jenkins Platform to CloudBees CI using the existing user account and $JENKINS_HOME directory

Follow these steps to migrate an operations center instance from CloudBees Jenkins Platform to CloudBees CI:

  1. Stop and disable your CloudBees Jenkins Platform operations center instance:

    sudo service jenkins-oc stop
sudo systemctl disable jenkins-oc
    ▼

  2. Install the operations center for CloudBees CI on traditional platforms.

  3. Stop your CloudBees CI operations center instance:

    sudo service cloudbees-core-oc stop
    ▼

  4. Migrate service options such as JENKINS_JAVA_OPTIONS, JENKINS_USER, and JENKINS_HOME from /etc/sysconfig/jenkins-oc to /etc/sysconfig/cloudbees-core-oc (or /etc/default/jenkins-oc to /etc/default/cloudbees-core-oc), per How to add Java arguments to Jenkins?.

    If on Debian or Ubuntu: when editing /etc/default/cloudbees-core-oc do not modify NAME this must remain as cloudbees-core-oc, Modify JENKINS_USER=jenkins-oc, JENKINS_GROUP=jenkins-oc and JENKINS_HOME=/var/lib/jenkins-oc.

    Confirm the differences by running:

    diff /etc/sysconfig/jenkins-oc /etc/sysconfig/cloudbees-core-oc
# or
diff /etc/default/jenkins-oc /etc/default/cloudbees-core-oc
    ▼

  5. Since the JENKINS_USER will use the previous value of jenkins-oc and your $JENKINS_HOME is not changing, you do not need to modify your $JENKINS_HOME directory, but we do have to correct ownership of other directories to account for using a non default JENKINS_USER, by running the command:

    # On RPM based distributions
sudo chown -R jenkins-oc:jenkins-oc /var/log/cloudbees-core-oc /var/cache/cloudbees-core-oc /etc/sysconfig/cloudbees-core-oc /usr/bin/cloudbees-core-oc
# on DEB based distributions
sudo chown -R jenkins-oc:jenkins-oc /var/log/cloudbees-core-oc /var/cache/cloudbees-core-oc /etc/default/cloudbees-core-oc
    ▼

  6. On RPM-based distributions, update the systemd configuration:

    sudo systemctl edit cloudbees-core-oc
    ▼

    Add the configuration to change the systemd service user to jenkins-oc (or your desired user account):

    [Service]
User=jenkins-oc
    ▼

  7. Start your new CloudBees CI operations center instance.

    sudo service cloudbees-core-oc start
    ▼

  8. Uninstall the CloudBees Jenkins Platform operations center:

    • On Ubuntu or Debian.

      sudo apt-get purge jenkins-oc
      ▼

    • On Red Hat, CentOS, Fedora or Amazon Linux 2.

      sudo yum remove jenkins-oc
      ▼

    • On OpenSUSE.

      sudo zypper remove jenkins-oc
      ▼

Option B: Migrating a client controller instance from CloudBees Jenkins Platform to CloudBees CI using the existing user account and $JENKINS_HOME directory

Follow these steps to migrate a client controller instance from CloudBees Jenkins Platform to CloudBees CI.

  1. Stop and disable your CloudBees Jenkins Platform client controller instance:

    sudo service jenkins stop
sudo systemctl disable jenkins
    ▼

  2. Install the client controller for CloudBees CI on traditional platforms.

  3. Stop your CloudBees CI client controller instance:

    sudo service cloudbees-core-cm stop
    ▼

  4. Migrate service options such as JENKINS_JAVA_OPTIONS, JENKINS_USER, and JENKINS_HOME from /etc/sysconfig/jenkins to /etc/sysconfig/cloudbees-core-cm (or /etc/default/jenkins to /etc/default/cloudbees-core-cm), per How to add Java arguments to Jenkins?.

    If on Debian or Ubuntu: when editing /etc/default/cloudbees-core-cm do not modify NAME; this must remain as cloudbees-core-cm. Modify JENKINS_USER=jenkins, JENKINS_GROUP=jenkins and JENKINS_HOME=/var/lib/jenkins.

    Confirm the differences by running:

    diff /etc/sysconfig/jenkins /etc/sysconfig/cloudbees-core-cm
# or
diff /etc/default/jenkins /etc/default/cloudbees-core-cm
    ▼

  5. Since the JENKINS_USER will use the previous value of jenkins and your JENKINS_HOME is not changing, you do not need to modify your $JENKINS_HOME directory, but we do have to correct ownership of other directories to account for using a non default JENKINS_USER, by running the command:

    # On RPM based distributions
sudo chown -R jenkins:jenkins /var/log/cloudbees-core-cm /var/cache/cloudbees-core-cm /etc/sysconfig/cloudbees-core-cm /usr/bin/cloudbees-core-cm
# on DEB based distributions
sudo chown -R jenkins:jenkins /var/log/cloudbees-core-cm /var/cache/cloudbees-core-cm /etc/default/cloudbees-core-cm
    ▼

  6. On RPM based distributions, update the systemd configuration:

    sudo systemctl edit cloudbees-core-cm
    ▼

    Add the configuration to change the systemd service user to jenkins (or your desired user account):

    [Service]
User=jenkins
    ▼

  7. Start your new CloudBees CI client controller instance:

    sudo service cloudbees-core-cm start
    ▼

  8. Uninstall the CloudBees Jenkins Platform client controller.

    • On Ubuntu or Debian:

      sudo apt-get purge jenkins
      ▼

    • On Red Hat, CentOS, Fedora or Amazon Linux 2:

      sudo yum remove jenkins
      ▼

    • On OpenSUSE:

      sudo zypper remove jenkins
      ▼

Advanced topic: Migrating to new machines at the same time as migrating CloudBees Jenkins Platform to CloudBees CI

If you would prefer to use a new machine, install CloudBees CI on it, and then migrate your $JENKINS_HOME data to this new machine, you must complete the following steps:

  1. Migrate to a new machine for the operations center at the same time as migrating CloudBees Jenkins Platform to CloudBees CI.

  2. Migrate to a new machine for client controller at the same time as migrating CloudBees Jenkins Platform to CloudBees CI.

Before proceeding, it’s important to determine the equivalent version of CloudBees CI for your currently installed version of CloudBees Jenkins Platform, as previously discussed in Determining the best migration and upgrade path for your team.

Migrating to a new machine for operations center at the same time as migrating CloudBees Jenkins Platform to CloudBees CI

  1. Provision a new machine for your operations center running a supported OS version. For more information, refer to Supported platforms for CloudBees CI on traditional platforms.

  2. For the desired CloudBees CI version on the new operations center machine, install the operations center for CloudBees CI on traditional platforms.

    For example, to install a specific version on Fedora/CentOS/RHEL, run:

    sudo yum install cloudbees-core-oc-2.346.4.1
    ▼

    To install a specific version on Debian/Ubuntu, run:

    sudo apt-get install cloudbees-core-oc=2.346.4.1
    ▼

  3. Stop the service:

    sudo service cloudbees-core-oc stop
    ▼

  4. Take the backup of your CloudBees Jenkins Platform $JENKINS_HOME data taken from your existing machine from /var/lib/jenkins-oc. Restore that onto the new machine running CloudBees CI at /var/lib/cloudbees-core-oc.

  5. After restoring, change the permissions of $JENKINS_HOME to use the new JENKINS_USER setting by running:

    sudo chown -R cloudbees-core-oc:cloudbees-core-oc /var/lib/cloudbees-core-oc
    ▼

  6. If you are changing the URL for your operations center, reset the identity of the operations center (you can skip this step if you are reusing the same URL):

    cd /var/lib/cloudbees-core-oc
rm secret.key* license.xml identity.key.enc
    ▼

  7. Check /var/lib/cloudbees-core-oc/config.xml and /var/lib/cloudbees-core-oc/jenkins.model.JenkinsLocationConfiguration.xml for URL specific options. Replace the Origin URL with the Target URL.

  8. If High Availability (HA) was enabled on the CloudBees Jenkins Platform operations center, remove the jgroups directory:

    cd /var/lib/cloudbees-core-oc
rm -r jgroups/
    ▼

  9. Migrate service options such as JENKINS_JAVA_OPTIONS from /etc/sysconfig/jenkins-oc (on the old machine) to /etc/sysconfig/cloudbees-core-oc (on the new machine) (or /etc/default/jenkins-oc to /etc/default/cloudbees-core-oc), per How to add Java arguments to Jenkins?.

  10. Start the service:

    sudo service cloudbees-core-oc start
    ▼

Migrating to a new machine for client controller at the same time as migrating CloudBees Jenkins Platform to CloudBees CI

  1. Provision a new machine for your client controller running a supported OS version. For more information, refer to Supported platforms for CloudBees CI on traditional platforms.

  2. For the desired CloudBees CI version on the new client controller machine, install the client controller for CloudBees CI on traditional platforms.

    For example, to install a specific version on Fedora/CentOS/RHEL, run:

    sudo yum install cloudbees-core-cm-2.346.4.1
    ▼

    To install a specific version on Debian/Ubuntu, run:

    sudo apt-get install cloudbees-core-cm=2.346.4.1
    ▼

  3. Stop the service:

    sudo service cloudbees-core-cm stop
    ▼

  4. Take the backup of your CloudBees Jenkins Platform $JENKINS_HOME data taken from your existing machines running CloudBees CI from /var/lib/jenkins. Restore that onto the new machines at /var/lib/cloudbees-core-cm.

  5. After restoring, change the permissions of $JENKINS_HOME to use the new JENKINS_USER setting by running:

    sudo chown -R cloudbees-core-cm:cloudbees-core-cm /var/lib/cloudbees-core-cm
    ▼

  6. Migrate service options such as JENKINS_JAVA_OPTIONS from /etc/sysconfig/jenkins (on the old machine) to /etc/sysconfig/cloudbees-core-cm (on the new machine) (or /etc/default/jenkins to /etc/default/cloudbees-core-cm), per How to add Java arguments to Jenkins?.

    Ensure any startup arguments that mention the old machine’s hostname are modified to the new machine’s hostname.

  7. Remove the connection details that point to the old CloudBees Jenkins Platform operations center:

    cd /var/lib/cloudbees-core-cm
rm license.xml operations-center-cloud* operations-center-client* com.cloudbees.opscenter.client.plugin.OperationsCenterRootAction.xml
    ▼

  8. If you are changing the URL for your client controller, reset the identity of the client controller (you can skip this step if you are reusing the same URL):

    cd /var/lib/cloudbees-core-cm
rm secret.key* license.xml identity.key.enc
    ▼

  9. Check /var/lib/cloudbees-core-cm/config.xml and /var/lib/cloudbees-core-cm/jenkins.model.JenkinsLocationConfiguration.xml for URL specific options. Replace the Origin URL with the Target URL.

  10. If HA was enabled on the CloudBees Jenkins Platform client controller, remove the jgroups directory:

    cd /var/lib/cloudbees-core-cm
rm -r jgroups/
    ▼

  11. Optionally, remove the build agents from the new controller. This should be done if you plan to keep the old CloudBees Jenkins Platform instance running at the same time as CloudBees CI. If you have CloudBees Jenkins Platform disabled and do not plan to start it again, this step can be skipped.

    This step is important so that the same build agents using the same remote work directories are not connected to two different client controllers, which would cause file collisions and corruption on the agent workspaces. 
    cd /var/lib/cloudbees-core-cm
rm -r nodes/*
    ▼

  12. Start the service:

    sudo service cloudbees-core-cm start
    ▼

  13. If you are not able to login to the client controller due to no connection to the operations center, disable security.

  14. Finally, we need to connect your new client controller to your new operations center.

    1. Navigate to the operations center web UI.

    2. Find the client controller item in question.

    3. Disconnect the client controller and release it if it is already connected.

    4. Use the Push connection details section to add the new client controller URL and select Push configuration to connect the client controller.

If you have any troubles with these steps, please contact CloudBees Support.

Migrating from Jenkins LTS to CloudBees CI on traditional platforms
Migrating managed controllers and team controllers