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_HOMEprior 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 , and enable jobs manually once you are ready to enable specific jobs and test running them.
-
Ensure that the Jenkins instance you want to migrate uses a supported JDK. For more information about supported versions of Java, 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 for controllers and Configuration as Code for the operations center.
For more information about JCasC, refer to 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 receive. This will help in identifying existing issues before the migration.
Video walk-through of this guide
Before beginning the migration process, you can watch this overview of the migration process.
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.
-
Go to
https://$JENKINS_URL/scriptand enterjenkins.model.Jenkins.instance.getLegacyInstanceId()to find yourInstance ID. Emailcsm-help@cloudbees.comand request a license for this Instance ID. -
Let all running builds complete before you begin to migrate.
-
Type the following command to stop your service.
sudo service jenkins stopStopping the service takes time. Ensure that the service is stopped before proceeding. -
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. -
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 sameJENKINS_HOMEfolder. -
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. -
If you are using RPM or DEB install methods, ensure the ownership of the
JENKINS_HOMEdirectory matches the user configured forJENKINS_USER. -
Start the new service.
-
Enter the license and save.
-
Sign in to CloudBees CI.
-
In the left pane, select Manage Jenkins, and then select Beekeeper Upgrade Assistant.
-
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.
-
Return to Manage Jenkins.
-
Select Manage Plugins.
-
On the Updates tab , upgrade all plugins, and then restart the instance.
Post-migration steps
-
Change SSH Build agents to Non-blocking I/O CloudBees SSH Build Agents plugin.
-
If you are not currently using Role-Based Access Control authorization, consider moving to it.
-
Configure your new instance. For recommended configuration settings, refer to: