Recommended Upgrade Strategy for CJOC and Client Masters


  • I have a CJP cluster with different CJOC and CJE versions. Which is the recommended upgrade strategy?


  • CloudBees Jenkins Operations Center
  • CloudBees Jenkins Enterprise


CJOC - CJE Compatibility

The most critical aspect when upgrading a CJP cluster is keeping all the nodes (both OC and client masters) within
the compatibility matrix, so that they can connect and communicate correctly.

The CJOC - CJE compatibility matrix is described in the
Support Lifecycle and Update Policies for CloudBees Jenkins Platform
document, but the most important rules of thumb (focusing on CJP 2.x) are summed up below:

  • The version of CJOC must be greater or equal than the version of any Client Master (CM) connected to it.

  • The version of every Client Master connected to the CJOC instance must be greater or equal than the oldest supported CM version
    for that CJOC version. For the currently supported CJOC versions the oldest supported Client Master versions are:

  • CJOC 2.7.x.y-rolling and 2.7.x.0.y-fixed: Oldest supported CJE version 1.642.1.1

  • CJOC 1.8.x: Oldest supported CJE version 1.642.1.1

Please be aware that the CJOC versions described above may be able to connect to older CJE versions, but
only CJE versions supported as of this writing (i.e., versions have not reached End-of-Life) have been considered.

Besides, the rules above imply that if you are using the 2.7.x.0.y-fixed train of CJOC you should not use Client Masters
in the 2.7.x.y-rolling train
as you may run into an unsupported configuration with the Client Master using
a newer version than the CJOC.

Upgrade Strategy

Below the recommended steps to perform an CJP cluster upgrade are described. To perform the actual upgrades
of the individual nodes please follow the instructions in
How to upgrade Jenkins

This KB article focuses in rolling upgrades, in which nodes in the CJP cluster are upgraded one by one with the goal
of having working instances between every step.

Step 1: Plan your Upgrade

CJP supports clusters with different CJOC and Client Masters versions, including having Client Masters in different versions
connected to the same CJOC instance. The only constraint is the compatibility matrix described above.

  • Collect the current versions of the different nodes.
  • Check the current configuration is a supported one.
  • Select the target versions for the different nodes. Every node may have different needs so this is a decision
    specific to each installation.

Step 2: Upgrade the cluster to a supported configuration (if needed)

If the initial state of the cluster is outside the compatibility matrix it is recommended that you first perform
a partial upgrade of the cluster so that it is in a supported configuration. For this:

  • If there is any CM older than the oldest supported Client Master version for the current CJOC, upgrade it
    to that oldest selected version.
  • If there is any CM newer than the newest supported Client Master version for the current CJOC:
    • Select the oldest CJOC version that is compatible with that CM.
    • If there is any CM older than the oldest supported for the selected CJOC version, upgrade them
      to that oldest version.
    • Upgrade the CJOC to the selected version.
  • Go back to Step 1, using the new current configuration.

Step 3: Perform the Upgrade

In this step we perform the actual upgrades. It is assumed than the initial state is a supported configuration.
If not, please go back to Step 2. As always, in each node upgrade follow the instructions detailed at
How to upgrade Jenkins

  • Check the oldest supported CM version for the target CJOC version:
  • For every current CM which is below this oldest supported version:
  • If the target version for the CM is supported by the current CJOC version upgrade the CM to its target version.
  • If not, upgrade the CM to the newest supported CM version of the current CM.
  • Upgrade the CJOC to its target version.
  • Upgrade every CM to its target version.

Have more questions?


Please sign in to leave a comment.