Issue
-
I would like to migrate all of my Jenkins jobs (or my entire Jenkins configuration) from one instance to another.
-
I would like to horizontally scale my current CloudBees CI configuration by moving jobs between controllers in order to distribute the workload.
Resolution
There are two ways to do this. Prior to attempting any CloudBees CI migration, please ensure your destination (new) instance meets with Prepare CloudBees CI for Support.
Case A - Migrate Jobs Only
This is the typical use case when an instance exceeds the recommendations from Cluster sizing and scaling. See also Right-sizing Jenkins controllers.
Please refer to Splitting a controller for this procedure.
Case B - Migrate Entire Jenkins Configuration, Including Jobs
This will preserve most (but not all) of your configuration. Some items (such as Agent connections or Credentials) will need to be re-created on the destination instance.
| When using this method, it will be necessary to obtain an updated license key from https://support.cloudbees.com. The license from your source/original instance will not work on the newly cloned test instance. |
If possible, enable Quiet Mode in the Origin controller -> then shutdown Origin controller -> then take a backup of $JENKINS_HOME. After the backup is complete and copied over to the Destination instance you can start the Origin instance and disable QuietMode. This will help starting the Destination clone instance in Quiet mode by default initially. Start the Destination instance in Quiet Mode.
|
1. Create a new controller on the target host, running the same version and same product. Ensure the connectivity is working as expected.
2. Backup the origin Controller’s JENKINS_HOME following Backup and restore.
Exclude the following files from the backup (see Explaining $JENKINS_HOME).
-
Reset the identity of the Controller:
-
$JENKINS_HOME/secret.key* -
$JENKINS_HOME/license.xml -
$JENKINS_HOME/identity.key.enc
-
-
In case HA (active/passive) is enabled, the
$JENKINS_HOME/jgroups/(subdirectory) This will only be present if the Source Controller is a member of a HA cluster -
Any Operations Center connection files (they are present in a Controller once it gets joined to an Operation Center), but may include:
-
$JENKINS_HOME/operations-center-cloud* -
$JENKINS_HOME/operations-center-client* -
$JENKINS_HOME/com.cloudbees.opscenter.client.plugin.OperationsCenterRootAction.xml
-
Check $JENKINS_HOME/config.xml and $JENKINS_HOME/jenkins.model.JenkinsLocationConfiguration.xml for URL specific options. Replace Origin URL by the Target URL.
Remove any agent connections and generate new connections to them. You can do this by just removing them from $JENKINS_HOME/nodes
Prepare your target instance to run in Quiet Mode. If you are migrating from Jenkins, you will not have access to the Quiet Start Plugin, instead refer to this article.
| Optionally, you can prevent a Build Storm in the target host by enabling Build Strategy "Initial Index Build Prevention" for all your Multibranch and Organization Folder project by running the skipInitiBuildIndex-multibranch.groovy in the origin host |
3. Restore the backup on the target instance following Backup and restore.
4. Upon startup, you will be prompted for Registration.
-
If you are connecting your new Test instance to an Operations Center (which is configured to centrally manage your licenses), you should be able to establish the connection.
-
If you would like to run your newly configured Controller in standalone (not connected to an Operations Center), please contact CloudBees and provide your instance ID to obtain a new license/registration. In the meantime, you may select the "Evaluation" option to proceed with the remaining steps prior to obtaining the license string.
5. If you would like all jobs to be disabled, run this script to disable all jobs. You can run scripts at the url, https://<jenkins-url>/script or by navigating to Manage Jenkins -> Script Console (requires Admin permissions), or by placing this script in JENKINS_HOME/init.groovy.d/:
```
Jenkins.instanceOrNull.allItems.each {
if (! it instanceof com.cloudbees.hudson.plugins.folder.Folder) {
it.setDisabled(true)
}
}
```
6. Navigate to 'Manage Jenkins' -> 'Configure System' and 'Configure Security' and update any settings as needed. Some settings (such as the Jenkins URL) are specific to each instance, and may need to be re-configured for your destination instance.
If needed, disable Security
7. It will be necessary to re-create the agents.
8. Migrate Credentials from the Origin instance. To recreate the Credentials in an automated way, you might want to review How to manage Credentials via the REST API, or Jenkins Credentials Migration.
9. Uncheck the Quiet start. You can toggle this via the URLs /quietDown and /cancelQuietDown. e.g: https://<jenkins-url>/cancelQuietDown.
If you are not using a CloudBees distributed release, you will not have access to the Quiet Start Plugin, instead refer to this article.
10. Start enabling jobs for testing (note: only enable jobs that will not have side effects on production platform - e.g. don’t update SCMs, publish artifacts to repositories, send notifications etc)
11. See the Best Strategy for Disk Space Management: Clean Up Old Builds article for recommendations on cleaning up old builds that are no longer required.
Case C - Migrating a Jenkins instance to a new machine
If you would like to migrate the entire instance to a new machine, and you are shutting down/removing the existing instance during that migration, the steps to follow are: Migrating a Jenkins instance to a new machine