Migrating from Jenkins LTS to CloudBees CI on traditional platforms

3 minute read

This guide shows you how to migrate a Jenkins instance to CloudBees CI on traditional platforms. Be sure to read all the information in Before you migrate prior to attempting the migration steps.

Before you migrate

Review the following important information before you begin the migration.

  • As all migrations carry a risk of data loss, CloudBees strongly recommends backing up your JENKINS_HOME prior to migrating. For more information, refer to the Backup and restore guide.

  • These migration steps should be performed in a 'test' environment before migrating your production instance. You will want to prevent Jenkins from starting new jobs after a restart to prevent your production jobs from triggering automatically when your test instance comes online, and once it’s online CloudBees recommends that you disable all jobs using Manage Jenkins Script console, and enable jobs manually once you are ready to enable specific jobs and test running them.

  • If the you are migrating from an instance of Jenkins LTS that was being run with JDK 11, switch to JDK 8 prior to migrating. For more information about supported platforms, refer to Supported platforms for CloudBees CI on traditional platforms - Java support.

  • The plugins you are using may need to be removed, upgraded, or in rare situations, downgraded. CloudBees recommends using the plugin versions in the CloudBees Assurance Program. Downgrading plugins can cause job or global configurations to become unreadable, so generally plugins should not be downgraded.

  • Please be aware that there are differences between Jenkins Configuration as Code (JCasC) and Configuration as Code (CasC) in CloudBees CI. For more information about CasC, refer to Configuration as Code (CasC) for Controllers and Configuration as Code (CasC) for Controllers

    For more information about JCasC, see Jenkins Configuration as Code.

  • Ensure that you install the Jenkins Health Advisor by CloudBees on Jenkins LTS before you migrate and review the first report you recieve. This will help in identifying existing issues before the migration.

Migrating to CloudBees CI on traditional platforms

The following steps show you how to migrate your Jenkins LTS instance to CloudBees CI on traditional platforms.

  1. Go to https://$JENKINS_URL/script and enter jenkins.model.Jenkins.instance.getLegacyInstanceId() to find your Instance ID. Email csm-help@cloudbees.com and request a license for this Instance ID.

  2. Let all running builds complete before you begin to migrate.

  3. Type the following command to stop your sevice.

    sudo service jenkins stop
    Stopping the service takes time. Ensure that the service is stopped before proceeding.
  4. Back up JENKINS_HOME.

    It is a good practice to check your backup manually to ensure that everything is as expected before you install CloudBees CI.
  5. Install CloudBees CI using the installation type of your choice (.rpm, .deb, .war, Docker) from https://docs.cloudbees.com/downloads. This new service must point to the same JENKINS_HOME folder.

  6. Migrate the settings from the Jenkins LTS config file (/etc/sysconfig/jenkins, /etc/default/jenkins, etc) to the CloudBees CI config file at the path for your product and OS, as listed in How to add Java arguments to Jenkins?.

    Ensure you carefully review the startup options you migrate in /etc/(sysconfig|default), to ensure they are still required and appropriate. Reach out to CloudBees Support if you are unsure.
  7. If you are using RPM or DEB install methods, ensure the ownership of the JENKINS_HOME directory matches the user configured for JENKINS_USER.

  8. Start the new service.

  9. Enter the license and save.

  10. Sign in to CloudBees CI.

  11. In the left pane, select Manage Jenkins, and then select **Beekeeper Upgrade Assistant.

  12. On the Beekeeper Upgrade Assistant page, in the left pane, select CAP Configuration, and then ensure that the Enroll this instance in the CloudBees Assurance Program checkbox is selected.

  13. Return to Manage Jenkins.

  14. Select Manage Plugins.

  15. On the Updates tab , upgrade all plugins, and then restart the instance.

Post-migration steps

Troubleshooting the migration from Jenkins LTS to CloudBees CI on traditional platforms

  • If the CloudBees CI service fails to start, ensure the JENKINS_HOME files are owned by the JENKINS_USER