Recommended Upgrade Strategy for operations center and client controllers

Article ID:230834347
3 minute readKnowledge base

Issue

  • I have a CJP cluster with different operations center and controller versions. Which is the recommended upgrade strategy?

Environment

  • CloudBees Jenkins Operations Center

  • CloudBees Jenkins Enterprise

Resolution

operations center - controller Compatibility

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

The operations center - controller 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 operations center must be greater or equal than the version of any client controller connected to it.

  • The version of every client controller connected to the operations center instance must be greater or equal than the oldest supported controller version for that operations center version. For the currently supported operations center versions the oldest supported client controller versions are:

  • operations center 2.7.x.y-rolling and 2.7.x.0.y-fixed: Oldest supported controller version 1.642.1.1

  • operations center 1.8.x: Oldest supported controller version 1.642.1.1

Please be aware that the operations center versions described above may be able to connect to older controller versions, but only controller 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 operations center you should not use client controllers in the 2.7.x.y-rolling train as you may run into an unsupported configuration with the client controller using a newer version than the operations center.

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 operations center and client controllers versions, including having client controllers in different versions connected to the same operations center 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 controller older than the oldest supported client controller version for the current operations center, upgrade it to that oldest selected version.

  • If there is any controller newer than the newest supported client controller version for the current operations center:

    • Select the oldest operations center version that is compatible with that controller.

    • If there is any controller older than the oldest supported for the selected operations center version, upgrade them to that oldest version.

    • Upgrade the operations center 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 controller version for the target operations center version:

  • For every current controller which is below this oldest supported version:

  • If the target version for the controller is supported by the current operations center version upgrade the controller to its target version.

  • If not, upgrade the controller to the newest supported controller version of the current controller.

  • Upgrade the operations center to its target version.

  • Upgrade every controller to its target version.