• Issue Summary
• Locate the required version of the CloudBees License Manager Plugin
• Upgrade the CloudBees License Manager Plugin
• Appendix A: Running Groovy Scripts

Issue Summary

If you are running a CloudBees Jenkins-based product with a version earlier than 2.176.1.4, your CloudBees software will not be compatible with licenses generated with the new certificate described in Preparing for the new CloudBees License Certificate. You must upgrade your CloudBees License Manager plugin to a version compatible with the new license certificate. Then you will be able to install a new license generated by the new certificate.

If you are running a CloudBees Jenkins-based product with a version of 2.176.1.4 or later, your software is already compatible with the new certificate. The only action needed in this case is to install a new license generated by the new certificate, as covered in Preparing for the new CloudBees License Certificate.

Locate the required version of the CloudBees License Manager Plugin

Find your current product version in the table below to see what version of the CloudBees License Manager plugin is required to enable compatibility with the new license certificate. CloudBees recommends applying the incremental upgrade revision indicated for your product version. You can also install the plugin manually as indicated in the instructions below. Either way, you will want to ensure that your system is running the target CloudBees License Manager plugin version indicated for your product version.

Releases of CloudBees Jenkins Platform Fixed line

Upgrade the CloudBees License Manager Plugin

You must update the CloudBees License Manager plugin for all installations of product versions earlier than 2.176.1.4. This includes any standalone controllers, client controllers, managed controllers, team controllers and operations center server instances. Be aware that this upgrade will involve a restart of each affected Jenkins controller or Operations Center instance.

As with any upgrade, you should follow these guidelines:
* We recommend that you first take a backup of your system before upgrading.
* We recommend that you test your upgrade procedure in a test environment prior to deploying the change in production.
* If you are running CloudBees Jenkins Platform or CloudBees Core, first upgrade your CloudBees Jenkins Operations Center.

To help you with the planning of the upgrade, CloudBees has provided a script you can use to check if your system is correctly upgraded. See the section titled Verify System Readiness for details on this script and how to run it.

Choose one of the methods below to upgrade the License Manager Plugin:

To upgrade using the incremental upgrade:

1. Enable Beekeeper to report the incremental update. Beekeeper normally recommends the next version, but you can run the script below to expose the Incremental Update.
   a. Navigate to the Script Console by choosing Manage Jenkins from the menu on the left and then Script Console from the Manage Jenkins page.
   b. Copy and paste the following lines into the text box provided:

   com.cloudbees.jenkins.plugins.assurance.props.BeekeeperProp.get().NO_FULL_UPGRADES.set()
   com.cloudbees.jenkins.plugins.assurance.CloudBeesAssurance.get().refreshStateSync()
   println "Success"
   

c. Click Run. You should see the word “Success” printed.
2. Apply the upgrade using Beekeeper
a. You will see a notification about the upgrade at the top of your screen.
b. Please see our documentation on the CloudBees Assurance Program for more information on how to apply this upgrade.

To upgrade using the manual installation method:

1. Download the plugin from the link provided for the target CloudBees License Manager Plugin version from the table above.
2. Upload the plugin to Jenkins.
   a. Navigate to the Jenkins Plugin Manager by selecting the Manage Jenkins menu option, and then the Manage Plugins option.
   b. On the Plugin Manager page, choose the Advanced tab.
   c. In the Upload Plugin section, select the plugin you downloaded to your computer in step 1, and then click “Upload”
3. Once the plugin is uploaded, restart Jenkins to complete the plugin installation.

Please note that this option will result in Beekeeper reporting a warning that you are running the wrong version of the CloudBees License Manager Plugin. You can ignore this warning.

To upgrade using the upgrade script:

Note: The script provides options for you to control how the script behaves. The documentation for those options is at the top of the script. We encourage you to run the script using the default values provided. You can run the script multiple times without side effects.

Use the steps below to run the script:

1. Download the upgrade-license-plugin.groovy script and open it in a local text editor.
2. Make any modifications to the options in the script and save it to disk.
3. Execute the script using either the Script Console or the Jenkins CLI. We recommend using the Jenkins CLI if you are upgrading a cluster of controllers connected to an operations center. See Appendix A: Running Groovy Scripts on how to do this if you are unfamiliar with running Groovy scripts.
4. Restart all upgraded Jenkins instances.

Verify the License Manager Plugin upgrade

After applying the plugin upgrade, you should verify that your installation is now running the target version of the CloudBees License Manager Plugin.

1. Navigate to the Jenkins Plugin Manager by selecting the Manage Jenkins menu option, and then the Manage Plugins option.
2. On the Plugin Manager page, select the Installed tab.
3. In the search box provided, search for “CloudBees License Manager”.

Compare the version of the CloudBees License Manager plugin listed on the Installed tab with the target version of this plugin from the table above. If they are the same version, you have successfully updated your Jenkins instance. Be sure to perform the same steps on all CloudBees Jenkins-based products, including all controllers and CloudBees Jenkins Operations Centers.

Alternatively, you can also run the Verify System Readiness script which will verify the upgrade is complete, including checking all connected controllers if running on an Operations Center.

Once this step is complete, your system is ready to apply the new license as described in Preparing for the new CloudBees License Certificate.

Appendix A: Running Groovy Scripts

At several points in this guide, we direct you to run different Groovy scripts. The instructions below provide a common set of instructions that can be used for all the Groovy scripts provided in this article.

Execute the script using either the Script Console or the Jenkins CLI. We recommend using the Jenkins CLI if you are upgrading a cluster of controllers connected to an operations center.

Using the Script Console

1. Navigate to the Script Console by choosing Manage Jenkins from the menu on the left and then Script Console from the Manage Jenkins page.
2. Copy and paste the script from your text editor into the text box provided.
3. Click Run.
4. Review the output and save it for future reference. If you need to open a support case with CloudBees, we will need the output from this script.

Using the Jenkins CLI

1. Read the Jenkins CLI guide if you are new to the CLI.
2. Ensure that your Jenkins API Token is configured correctly.
3. Download the jenkins-cli.jar.
4. Run the script at the command line:
   1. java -jar jenkins-cli.jar -auth myusername:<MY API TOKEN> -s https://<MY JENKINS URL> groovy = < <SCRIPT FILE NAME>.
      a. For example: java -jar jenkins-cli.jar -auth myusername:abcd1121d3fb02896a101c1d5e -s https://myjenkins.corp groovy = < upgrade-license-plugin.groovy.
   2. Review the output from the script provided and save it for future reference. If you need to open a support case with CloudBees, we will need the output from this script.