Upgrading CloudBees CI on traditional platforms

On this page

Before upgrading
Recommendations
Upgrade process
Post-upgrade notes

Before upgrading

Take a SNAPSHOT of your CloudBees CI platform. For the Operations Center and every Master:

Generate a support bundle. It will help in case there are problems with the upgrade or to know what plugins were upgraded in the process.
Backup your instance before starting the upgrade. The minimal backup is a copy of your ${JENKINS_HOME} directory. If the BUILD_DIRECTORY is out of the ${JENKINS_HOME}, you must back it up as well.

Note: In the case something unexpected happens, the rollback process in based on the Backup of your instance.

For Client Master connected to Operations Center:

Operations Center must be upgraded first, then Client Masters.
Starting with CloudBees Jenkins Platform 2.7 and for all versions of CloudBees CI on traditional platforms, the version of Operations Center must always be more recent or as old as the version of the Client Masters that are connected to the Operations Center (Operations Center >= Client Master version).
The Client Master connected to a Operations Center does not have to be at the same version.

Recommendations

Test environment

This is ideally a fully test environment with a Operations Center and Client Masters. This requires a test license. If this is not feasible, just having a test master with representative jobs is better than nothing.

Enable CloudBees Assurance Program

Ensure that CloudBees Assurance Program is enabled to avoid plugin dependency issues or incorrect versions installed.

Upgrade to latest version

It is recommended always to upgrade to the latest version of your CloudBees product, ensuring a wider lifecycle support coverage plus more security patches added (CloudBees Security Advisory), more fixed issues, and more new features included.

`JENKINS_HOME` should be in the same location

It is highly recommended to upgrade Jenkins to the same location where it is running even if it is 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 agent 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.

Stop using Apache Maven builds (if it is possible)

Maven plugin plugin is not recommended as it is often considered evil by the Community. Therefore, it is recommended that you migrate jobs using this plugin to Pipeline Jobs with the Maven integration.

If (and only if) you are able to migrate your Maven plugin builds, please read carefully the Maven jobs and Java versions compatibility guide.

Upgrade process

Visit CloudBees downloads

Go to the downloads page. Select your desired distribution type, and review the instructions.

WAR
RPM
OpenSuse
Debian
Microsoft Windows
Docker

Installation procedures

WAR

If your CloudBees CI instance is run with the command java -jar cloudbees-core-cm.war or java -jar cloudbees-core-oc.war, you can simply replace the jenkins.war file with the latest version.

Linux

Red Hat / CentOS

Master - yum upgrade cloudbees-core-cm
Operations Center - yum upgrade cloudbees-core-oc

IMPORTANT: RPM/YUM with High Availability

The RPM package contains a post-install script to ensure ownership on several files including JENKINS_HOME. Therefore if High Availability is setup, this could lead to I/O Errors - for example when upgrading one node while another one is still running. More information is available in JENKINS-23273.

To workaround this problem, you can skip this script by adding the property JENKINS_INSTALL_SKIP_CHOWN="true" under /etc/sysconfig/jenkins.

Debian / Ubuntu

Master - apt-get update && apt-get install cloudbees-core-cm
Operations Center - apt-get update && apt-get install cloudbees-core-oc

openSUSE / SUSE Linux

Master - zypper install cloudbees-core-cm
Operations Center - zypper install cloudbees-core-oc

Servlet container

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

When using servlet containers, CloudBees CI will set the JENKINS_HOME to the $APP_SERVER_USER/.jenkins/ 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.

Tomcat

Use 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.

It is recommended to configure it in the script $CATALINA_BASE/bin/setenv.sh (Linux) or %CATALINA_BASE%\bin\setenv.bat (Microsoft Windows) that you’ll create to customize your application server.

Custom container installations

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

Microsoft Windows

To upgrade on Microsoft Windows servers, a new .zip must be downloaded from the downloads page and installed.

Post-upgrade notes

In case, JNLP agents (specifically for Microsoft Windows) are not able to connect, review the article Windows agent offline or unable to connect.

Review articles in our Best Practices and apply changes accordingly.