Migration Guide: CloudBees CI

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.

Environment

Resolution

There are two ways to do this. Prior to attempting any Jenkins migration, please ensure your destination (new) Jenkins instance meets with Prepare Jenkins for Support — CloudBees Support.

Case A - Migrate Jobs Only

This is the typical use case when a Jenkins instance exceeds the recommendations from CloudBees controller Sizing Guidelines. See also Right-sizing Jenkins controllers.

Please refer to CloudBees Docs: Splitting a controller for this procedure.

Case B - Migrate Entire Jenkins Configuration, Including Jobs

Option A - Just Migration

This will preserve most (but not all) of your Jenkins configuration and other settings. Some items (such as Agent connections or Credentials) will need to be re-created on the destination instance. Note, that in using this method, it will be necessary to contact CloudBees Support (Licensing) to obtain an updated license key. The instance ID (and associated license string) from your source/original Jenkins instance will not work on the newly cloned TEST instance.

Please follow this procedure:

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 fresh intance in the Target Host, running the same version and same product of the CloudBees CI. Ensure the connectivity is working as expected.

2. Backup the Origin Controller $JENKINS_HOME. Refer to [Backup and restore

CloudBees Docs](https://docs.cloudbees.com/docs/cloudbees-ci/latest/backup-restore/)

For Operation Center it requires a Manual Backup
For Controller use the Backup plugin

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 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 not using a CloudBees distributed release, you will not have access to the Quiet Start Plugin, instead refer to this article.

3. Restore the prepared Backup for the migration

For Operation Center it requires a Manual Restore
For Controller use the Restore job
For Managed Controller, it is required Restart the Controller to regenerate the Statefulset.

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. Immediately 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. This requires Admin permissions.

```
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 nodes, including Agent or Shared Agent connections. If any issues arise, please check (and repeat, if needed) step #4. If any of these files are corrupted, or the original copies weren’t replaced with new versions once the Destination instance was started…issues might arise in creating Agent connections.

8. Migrate Credentials from the Origin instance. To recreate the Credentials in an automated way, you might want to review Creating credentials using Groovy and How to manage Credentials via the REST API.

9. Uncheck the Quiet Restart. 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. Please see the Deleting Old Builds - Best Strategy for Cleanup and disk space management article for recommendations on configuring job settings following migration to your newly cloned TEST instance.

Option B - Migration and Upgrade

1 Fresh installation to latest the version of the product in [DESTINATION]. Important: Enroll this instance in the CloudBees Assurance Program and Allow automatic upgrades of plugins on restart.

2 Verify the product is running fine in [DESTINATION].

3 Stop [DESTINATION] instance.

4 Backup [DESTINATION] JENKINS_HOME

5 Apply steps from previous option Migrate Entire Jenkins Configuration up to step #6.

6 [DESTINATION] Update the variable JENKINS_HOME to the "Migrated JENKINS_HOME".

7 Apply steps in Migrate Entire Jenkins Configuration starting from step #7.

The content A. Before Upgrading in Upgrade Guide: CloudBees Jenkins Platform and Team is applicable here too.