Migrating from CloudBees Jenkins Team to CloudBees Jenkins Distribution


CloudBees Jenkins Team is no longer being maintained. A software migration to CloudBees Jenkins Distribution is needed to continue receiving security updates. CloudBees Jenkins Distribution is free to use, including the Beekeeper Upgrade Assistant, set of recommended plugins, and CloudBees Jenkins Advisor.

The migration process occurs in two phases:

Before the migration

A few days before the migration, prepare your CloudBees Jenkins Team instance before you start the actual migration:

Required actions

For a successful migration, you must take the following actions before migrating:

  1. Let the Support Team know about your upgrade plans:

    1. Open a support issue at Submit a request

    2. Provide the information detailed in Required Data: Assisted Update.

  2. Make sure your intended migration target is supported:

  3. Ensure your CloudBees Jenkins Distribution environment is set up for support:

    1. Make sure CloudBees Jenkins Team is set up in line with the recommendations in the Jenkins instance is prepared for support article.

    2. The GC and ulimit values are critical for good Jenkins performance and to avoid crashes. Pay particular attention to the settings for Java Parameters, Ulimit Settings, Log Startup Timing Info.

  4. Take a snapshot of your current CloudBees Jenkins Team instance:

    1. Generate a support bundle with your CloudBees Jenkins Team instance’s current state. If there are problems with the migration, it will help to know what plugins were upgraded in the process.

    2. Back up your instance before starting your upgrade. The minimal backup is a copy of your ${JENKINS_HOME} directory. If the BUILD_DIRECTORY is in a different location than ${JENKINS_HOME}, you must back up that location as well.

Review the following optional steps to enhance your migration.

  1. Don’t perform a migration of your production environment before testing the migration in a test environment. Review the recommendations in Architecting for Manageability.

  2. Enable CAP: Ensure that CAP is enabled to avoid plugin dependency issues or incorrect versions.

  3. Make sure $JENKINS_HOME is in the same location where it is running, even in the production environment. Doing a backup of $JENKINS_HOME and the $BUILD_DIR — in case it is outside the default location — should be enough to revert to the previous status.

    It is not recommended to keep two different instances working at the same time to avoid downtime while performing the upgrade unless you really know what you are doing. It will be very difficult to replicate the exactly same environment.

    • JNLP slave will not work correctly as the $JENKINS_URL location will be different

    • Credentials might fail in case the secret is not the same on both instances

    • The OS might not be configured in the same way. i.e ulimit

    • The Jenkins configuration might not be correctly replicated

Check the impact of the changes

  1. Read the CloudBees Release Notes for the product versions between your current version of CloudBees Jenkins Team and CloudBees Jenkins Distribution. Each product release/revision page provides details about New Features and Known and Resolved issues fixed. Besides, there is other valuable information into tabs:

    • INFO: Release Date and Jenkins LTS is based on.

    • Security Advisories: Security Advisories. Security features may result in deliberate changes to the behavior of core or certain plugins.

    • Plugin Tab: Plugins versions and their Tiers.

Exceptions and considerations

  • Maven jobs might be affected as they are required now to be using the same Java version than the Master is running. The work-around is explained on this knowledge base article. Verify this work-around on a test environment.

  • Removal of the AJP connector from the embedded Winstone-Jetty container

  • The container must be Servlet 3.1 (Java EE 7) compliant: Apache Tomcat 8, Wildfly 8, Glassfish 4, Websphere 9.

  • Support for all TLS versions before 1.2 has been dropped. If you’re using the embedded Jetty container’s HTTPS functionality, it will no longer accept TLS 1.0 or 1.1 connections.

The migration

Red Hat / CentOS migration

To migrate from CloudBees Jenkins Team to CloudBees Jenkins Distribution on Red Hat Enterprise Linux or CentOS systems, follow these instructions.

Remove the previously installed cjt package

Replace the previously installed cjt package with the cloudbees-jenkins-distribution package:

yum remove cjt (1)
ln -s /var/lib/cjt /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed cjt package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for Red Hat Enterprise Linux / CentOS

Administrators running Red Hat-based distributions, such as Red Hat Enterprise Linux, Fedora, Oracle Linux, and CentOS, first need to set up the RPM repository for CloudBees Jenkins Distribution and import the key.

  1. Set up the RPM repository:

    sudo wget -O /etc/yum.repos.d/cloudbees-jenkins-distribution.repo https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees-jenkins-distribution.repo
  2. Import the CloudBees key:

    sudo rpm --import https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees.com.key
    Note
    If the CloudBees key has already been imported on the machine, the rpm --import command will fail. This error can be safely ignored.
  3. Once the repository and key have been set up, CloudBees Jenkins Distribution can be installed with yum via:

    sudo yum install cloudbees-jenkins-distribution
  4. Set the cloudbees-jenkins-distribution service to automatically start on boot:

    sudo chkconfig --add cloudbees-jenkins-distribution
    sudo /etc/init.d/cloudbees-jenkins-distribution start

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/cjt

Confirm settings

Any changes you made to /etc/sysconfig/cjt are saved to /etc/sysconfig/cjt.rpmsave when the cjt package is removed. If necessary, manually review this file, and copy the appropriate settings into /etc/sysconfig/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, you can start CloudBees Jenkins Distribution with the command service cloudbees-jenkins-distribution start.

openSUSE / SUSE Linux migration

To migrate from CloudBees Jenkins Team to CloudBees Jenkins Distribution on openSUSE or SUSE Linux systems, follow these instructions.

Remove the previously installed cjt package

Replace the previously installed cjt package with the cloudbees-jenkins-distribution package:

zypper remove cjt (1)
ln -s /var/lib/cjt /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed cjt package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for openSUSE / SUSE Linux

Use the zypper command to install CloudBees Jenkins Distribution on openSUSE-based distributions.

  1. First, add the CloudBees RPM repository:

    sudo zypper addrepo -f https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/opensuse/ cloudbees-jenkins-distribution
  2. Next, run:

    sudo zypper install cloudbees-jenkins-distribution

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/cjt

Confirm settings

Any changes you made to /etc/sysconfig/cjt are saved to /etc/sysconfig/cjt.rpmsave when the jenkins package is removed. If necessary, manually review this file, and copy the appropriate settings into /etc/sysconfig/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, you can start CloudBees Jenkins Distribution with the command service cloudbees-jenkins-distribution start.

Debian / Ubuntu migration

To migrate from CloudBees Jenkins Team to CloudBees Jenkins Distribution on Debian or Ubuntu systems, follow these instructions.

Remove the previously installed cjt package

Replace the previously installed cjt package with the cloudbees-jenkins-distribution package:

apt-get remove cjt (1)
ln -s /var/lib/cjt /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed cjt package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for Debian / Ubuntu

Administrators running Debian-based distributions such as Debian or Ubuntu will need to add an APT repository and key in order to install CloudBees Jenkins Distribution.

  1. To use the Debian package repository of CloudBees Jenkins Distribution to automate installation and upgrade, first add the key to your system:

    wget -q -O - https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian/cloudbees.com.key | sudo apt-key add -
  2. Edit /etc/apt/sources.list and add the entry for CloudBees Jenkins Distribution:

    deb https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian binary/
  3. Update your local package index:

    sudo apt-get update
  4. Install CloudBees Jenkins Distribution:

    sudo apt-get install cloudbees-jenkins-distribution
    Caution
    Older versions of Debian and Ubuntu do not provide a Java 8 package and CloudBees Jenkins Distribution may fail to install as a result. Using newer versions of these distributions which provide Java 8 is strongly recommended.
  5. Start the cloudbees-jenkins-distribution service:

    service cloudbees-jenkins-distribution start

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/cjt

Confirm settings

If you made changes to /etc/default/cjt, review this file, and copy the appropriate settings into /etc/default/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, you can start CloudBees Jenkins Distribution with the command service cloudbees-jenkins-distribution start.

Docker

To migrate from CloudBees Jenkins Team to CloudBees Jenkins Distribution on Docker-based systems, follow these instructions:

Stop and delete the previously installed container service

Stop and delete the previously installed container service and update it with an appropriate Docker image.

docker stop <CloudBees jenkins Team container name> && docker rm <CloudBees jenkins Team container name> (1)
docker pull cloudbees/cloudbees-jenkins-distribution (2)
docker run --name <CloudBees jenkins Team container name> -p 18080:8080 -v /tmp/docker/:/var/cloudbees-jenkins-distribution [IMAGE_ID] (3)
  1. This command stops and deletes the previous container.

  2. This command pulls a new Docker image from CloudBees.

  3. This command launches a container from the new image with the same name (<CloudBees jenkins Team container name>) and same JENKINS_HOME volume.

After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default, and you can move on to the post-migration tasks.

Note
If you are using a CloudBees Jenkins Distribution prior to 2.176.2.3 use /var/jenkins_home instead of /var/cloudbees-jenkins-distribution

Using a custom servlet container

Once a WAR archive has been downloaded, follow the servlet container’s existing application deployment process.

When using servlet containers, CloudBees Jenkins Distribution sets JENKINS_HOME to the $APP_SERVER_USER/.cloudbees-jenkins-distribution/ folder. If the servlet container installation does not include write permissions to this folder for this user (sometimes done for security), you either need to grant appropriate permissions or override this setting by adding the "-DJENKINS_HOME=$MY_JENKINSPATH" argument in your servlet container startup. Refer to the servlet container’s documentation for how to add startup arguments.

Custom container installations

If you use a custom container, you will find the jenkins.war file in the deploy directory of your container. For example, /usr/local/jboss/server/default/deploy/jenkins.war would be the location for a default JBoss installation.

Tomcat

Configure TomCat in the script $CATALINA_BASE/bin/setenv.sh (Linux) or %CATALINA_BASE%\bin\setenv.bat (Microsoft Windows) that you create to customize your application server.

Use the environment variable CATALINA_OPTS to add:

  • -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true.

  • -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true which is needed for Blue Ocean.

Windows migration

To migrate from CloudBees Jenkins Team to CloudBees Jenkins Distribution on Microsoft Windows systems, follow these instructions.

Remove the previously installed cjt package

Replace the previously installed cjt package with an appropriate Microsoft Windows MSI:

  1. Stop the cjt service and delete it.

  2. Rename the folder where the jenkins service was running from Program Files (x86)/Cjt to Program Files (x86)/CloudBeesJenkinsDistribution.

    Note
    Folder names may vary depending on where CloudBees Jenkins Team was installed.

Install and run CloudBees Jenkins Distribution for Windows

To run CloudBees Jenkins Distribution on Microsoft Windows, use the MSI file from the CloudBees Jenkins Distribution download site.

  1. Download the cloudbees-jenkins-distribution.zip file, and the SHA256 checksum file.

  2. The checksum file can be used to verify that the cloudbees-jenkins-distribution.zip is correct. Compare the contents of cloudbees-jenkins-distribution.zip.sha256 with the output of the following PowerShell command:

    $(CertUtil -hashfile D:\Users\USER\Downloads\cloudbees-jenkins-distribution.zip SHA256)[1] -replace " ",""
  3. Unpack the archive and execute the CloudBees Jenkins Distribution installer, cloudbees-jenkins-distribution.msi.

    Note
    The CloudBees Jenkins Distribution installer for Microsoft Windows requires a 64-bit operating system and a compatible .NET framework (2.0, 3.5.1, 4.0) in order to be installed as a service. Most Microsoft Windows versions install a compatible framework by default.

After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default.

WAR migration

While it is strongly recommended that administrators rely on native packages, CloudBees Jenkins Distribution can be run as a stand-alone WAR file with an existing JENKINS_HOME.

Install and run CloudBees Jenkins Distribution for stand-alone WAR files

  1. Download the WAR file for CloudBees Jenkins Distribution; for your operating system and copy it to where you wish to run CloudBees Jenkins Distribution.

  2. Copy the file to the directory where you wish to run CloudBees Jenkins Distribution.

  3. Open a terminal and run the command:

    java -jar cloudbees-jenkins-distribution.war
  4. The process output generates a password offset by three rows of asterisks above and below the text. Copy the password. The password is also saved in a directory like /users/<username>.jenkins/secrets/initialAdminPassword, where username is replaced with your username. The exact path may vary depending upon your operating system.

    *************************************************************
    *************************************************************
    *************************************************************
    
    Jenkins initial setup is required. An admin user has been created and a password generated.
    Please use the following password to proceed to installation:
    
    d661ea28c6b94406ad627601b6f4aa877
    
    This may also be found at: /Users/<username>/.jenkins/secrets/initialAdminPassword
    
    *************************************************************
    *************************************************************
    *************************************************************
  5. The terminal portion is complete when the output reads:

    INFO: Obtained the updated data file for hudson.tools.JDKInstaller
    Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get
    INFO: Beekeeper is parsing UpdateSite cloudbees-jenkins-distribution-offline
    Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get
    INFO: Beekeeper is parsing UpdateSite cap-cloudbees-jenkins-distribution
    Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run
    INFO: Started telemetry collection
    Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run
    INFO: Finished telemetry collection. 1 ms

To complete the migration, set the JENKINS_HOME environment variable to the existing Jenkins home directory of CloudBees Jenkins Team. For example:

shell% JENKINS_HOME=/var/lib/cjt java -jar cloudbees-jenkins-distribution.war