Migration Guide - CloudBees CJD to CloudBees CI on traditional platforms

Article ID:360059820851
4 minute readKnowledge base

Issue

  • I would like to migrate current CloudBees Jenkins Distribution to CloudBees CI.

Environment

  • CloudBees Jenkins Distribution

Resolution

This article will cover the migration process from CloudBees Jenkins Distribution to CloudBees CI on different platforms. Please note that once you migrate the instance to CI, as CI is a paid solution unlike CloudBees Jenkins Distribution, a CloudBees License will be required to access the CI instance. This license has to be purchased separately. This has to be requested by raising a Support Ticket with CloudBees. You can raise a Support Ticket here. We recommend contacting CloudBees Support before starting the migration process so the License request and other doubts are addressed before.

Please note that this guide will cover the migration process from CJD to the same version of CI. If an upgrade is required, you may proceed with an assisted upgrade as usual.

Case A - Migration using Docker Compose

  • Stop the container.

  • Create a backup of the current docker-compose.yml file and also the $JENKINS_HOME/ folder from the container volume.

  • Open the docker-compose.yml and change the current docker image from image: cloudbees/cloudbees-jenkins-distribution:2.249.2.4 to the target one image: cloudbees/cloudbees-core-cm:2.249.2.4. Ensure you are indicating the version tag so you avoid getting the latest release. This will also avoid potential issues when a new version is released. The target version details can be obtained from https://hub.docker.com/r/cloudbees/cloudbees-core-cm/tags?page=1&ordering=last_updated.

  • The $JENKINS_HOME/ folder for CJD is called cloudbees-jenkins-distribution, while on cloudbees-core-cm is jenkins_home, so you will also need to update the path on your volume. If this is not updated, a new instance will come up on a different $JENKINS_HOME/ folder, so you will see an empty instance without any of your previous data.

  • To avoid permission issues, you can grant permissions on the volume folder to the user that will be running Jenkins by running the following command: chmod 700 foldername. Additionally, you can change the owner by running chown -R cloudbees-core-cm: foldername.

  • Once the docker-compose.yml changes have been done, you need to delete the below items from the $JENKINS_HOME folder on your volume to prevent issues when the new instance starts after the migration.

    • $JENKINS_HOME/cb-envelop folder.

    • $JENKINS_HOME/war folder.

    • $JENKINS_HOME/update folder.

    • hudson.model.UpdateCenter.xml file

  • It is recommended to delete the previous container by running docker container rm [container_id], if it was not previously removed.

  • Launch your instance again as usual.

Case B - Migration using Docker

The process using Docker will be similar to the one described above:

  • Stop the container by running docker stop [container_id].

  • Create a backup of the current $JENKINS_HOME/ folder from the container volume.

  • Change the current docker image on your command you are using to start Jenkins from image: cloudbees/cloudbees-jenkins-distribution:2.249.2.4 to the target one image: cloudbees/cloudbees-core-cm:2.249.2.4. Ensure you are indicating the version tag so you avoid getting the latest release. This will also avoid potential issues when a new version is released. The target version details can be obtained from https://hub.docker.com/r/cloudbees/cloudbees-core-cm/tags?page=1&ordering=last_updated.

  • The $JENKINS_HOME/ folder for CJD is called cloudbees-jenkins-distribution, while on cloudbees-core-cm is jenkins_home, so you will also need to update the path on your volume. If this is not updated, a new instance will come up on a different $JENKINS_HOME/ folder, so you will see an empty instance without any of your previous data.

  • To avoid permission issues, you can grant permissions on the volume folder to the user that will be running Jenkins by running the following command: chmod 700 foldername. Additionally, you can change the owner by running chown -R cloudbees-core-cm: foldername.

  • Delete the below items from the $JENKINS_HOME folder on your volume to prevent issues when the new instance starts after the migration.

    • $JENKINS_HOME/cb-envelop folder.

    • $JENKINS_HOME/war folder.

    • $JENKINS_HOME/update folder.

    • hudson.model.UpdateCenter.xml file

  • Delete the previous container by running docker container rm [container_id].

  • The changes should look like below:

  • Launch your instance again as usual.

Command used for CJD:

docker run \
  -u root \
  --rm \
  -d \
  -p 8080:8080 \
  -p 50000:50000 \
  -v /home/user/jenkins/cjd:/var/cloudbees-jenkins-distribution \
  cloudbees/cloudbees-jenkins-distribution:2.249.2.4

Command used for CI:

docker run \
  -u root \
  --rm \
  -d \
  -p 8080:8080 \
  -p 50000:50000 \
  -v /home/user/jenkins/cjd:/var/jenkins_home \
  cloudbees/cloudbees-core-cm:2.249.2.4

Case C - Migration using war file

The process using a war file will be similar to a regular upgrade.

  • You can get the target war file from the CloudBees downloads page.

  • Stop the Jenkins service or the command running Jenkins.

  • Create a backup of the current $JENKINS_HOME/ folder.

  • Replace the CJD jenkins.war file from $JENKINS_HOME/ with the CI one downloaded previously.

  • Delete the $JENKINS_HOME/cb-envelope on your volume. This will prevent issues when the new instance starts after the migration.

  • Start the service again or launch the java command.

Additional steps

  • Once the instance is up and running, although the agents items will be there, you will need to reconnect each one from each agent host.

  • It is recommended to run a round of testing with the main jobs in the instance to confirm that the jobs are being build successfully.

Error logs

If you find the below error in the logs when your instance is starting, this was probably caused by the $JENKINS_HOME/cb-envelope folder not being removed:

SEVERE c.c.j.p.u.envelope.LoggerLog#log: Starting product [core-cm] over installed [cloudbees-jenkins-distribution] metadata not supported

In case you spot errors similar to the one below, you may be facing permissions issues. Please ensure the user running Jenkins has permissions on the volume/$JENKINS_HOME folder. If you already granted permissions, you may want to change the owner as well and ensure the permissions are correctly granted.

WARNING	h.i.i.InstallUncaughtExceptionHandler#handleException: Caught unhandled exception with ID 36fdeec1-9607-40c9-86c6-f9e5819d58b8
org.apache.commons.jelly.JellyTagException: file:/var/jenkins_home/war/WEB-INF/classes/lib/layout/pageHeader.jelly:8:75: <st:include> No page found 'ossPageHeader.jelly' for class hudson.util.HudsonFailedToLoad

References