• Issue Summary
• Action Required
  • Apply the New License
  • Verify System Readiness
• Appendix A: Running Groovy Scripts

Issue Summary

On June 22nd, 2020, the certificate used to sign all existing CloudBees licenses for Jenkins-based products will expire. This certificate is used to verify the authenticity of the customer’s CloudBees license.

Customers must install a new license (generated with the new certificate) before June 22, 2020. Existing licenses will become invalid as of June 22, 2020.

This issue applies to the following CloudBees products:

• CloudBees Core on traditional platforms
• CloudBees Core on modern cloud platforms
• CloudBees Jenkins Enterprise
• CloudBees Jenkins Platform
• CloudBees Jenkins Distribution

Action Required

Global Overview

Applying the new license, in general terms, consists of the following steps:
1. Checking your system capabilities to install the new license. This step will be detailed discussed in Verify System Readiness. You may iterate this step if required.
2. Once you have your system ready to install the new license, it is time to choose one of the methods below to apply the new license following the instructions detailed in Apply the New License.
3. It is highly recommended checking your system status after applying the new license. To do so, follow the detailed instructions listed in Verify System Readiness again.

Verify System Readiness

CloudBees has provided a verify-system-readiness.groovy script to verify if your system is ready for the license certificate expiration on June 22nd. This script will verify that your software is compatible with the new license certificate and has been upgraded if required. The script will also tell you if a new license generated using the new license certificate has been correctly applied. If run on Operations Center, the script will perform these checks on all connected masters in addition to the Operations Center itself.

This script does not make any changes to your CloudBees Jenkins or Operations Center cluster.

Follow these instructions to run the script:

1. Download the verify-system-readiness.groovy script 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 masters connected to an operations center. See Appendix A: Running Groovy Scripts on how to do this if you are unfamiliar with running Groovy scripts.
   Once the script completes, you will see output similar to the following:

   01-script-status running...
   Determining the instance type...Operations Center
   Operations Center
   Asking for the status of the connected masters...
   \[master1\]
   \[master2\]
   01-script-status complete
   -----------------------------------------------------------------------------------------
   SUMMARY
   -----------------------------------------------------------------------------------------
   Operations Center - cloudbees-license plugin 9.24 is installed. The plugin must be updated in this instance before installing the new license.
   master1 - cloudbees-license plugin 9.24.1 is installed. This instance is ready to install the new license.
   master2 - cloudbees-license plugin 9.24 is installed. The plugin must be updated in this instance before installing the new license.
   You have one or more instances that need to be upgraded.
   

How to interpret the output

Depending on the version of CloudBees Jenkins you are using, the output shown will vary based on a number of factors. The key points are:

• If the license plugin for Operations Center or a master needs to be upgraded
• If a new license needs to be applied

If a Jenkins instance has the required license plugin version installed, and the updated license has been installed, you will see a message indicating that the instance is up-to-date and you don’t need to perform any action on this Jenkins instance regarding the new CloudBees License.

Example: Operations Center - cloudbees-license plugin 9.36 is installed. This instance is up to date and running the new license.

Others possible outputs reported by this script:
* The plugin must be updated in this instance before installing the new license - You will need to update your cloudbees-license plugin.
* This instance is ready to install the new license - The cloudbees-license plugin is up-to-date and you can install the new license in this instance.
* Is not installed. The plugin must be installed in this instance before updating the license - The cloudbees-license plugin is not installed in your Jenkins instance and you will need to install it in order to update the license.
* This instance is in an inconsistent state. - If you receive this error, please contact CloudBees Support Team to address the issue.

In any case, do not hesitate contacting CloudBees Support Team if you have any problems. We will be happy to assist you.

Apply the New License

Choose one of the methods below to apply the new license:

Note: Applying the new license will not disrupt the behavior or availability of your system.

To apply the new license by using a script:

1. Download the apply-license.groovy script and open it in a 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 masters 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. Once the script has been run, it should print a message saying that the new license has been successfully applied.

Note that connected masters will retrieve a new license over the course of the 6 hours after the license is updated on Operations Center.

To manually request and apply the new license:

1. Retrieve the Instance ID from your Operations Center or standalone CloudBees Jenkins Master.
2. Email csm-help@cloudbees.com to request a replacement license. Please provide the instance ID in your email. This will create a new support case to track your request.
3. Once you receive the new license, navigate to the master or operations center where you retrieved the instance ID.
4. Navigate to the Manage License screen by clicking Manage Jenkins and then selecting Manage License.
5. On the Manage License screen, enter the License Key and License Certificate provided in response to your support request.
6. Click Save.

Note that connected masters will retrieve a new license over the course of the 6 hours after the license is updated on Operations Center.

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 masters connected to an operations center.

To run Groovy scripts 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.

To run Groovy scripts 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.

Contact with the CloudBees Support Team

In case you need to submit a ticket with the CloudBees Support Team, in order to speed up the response time, any question, verification or troubleshooting request should follow the steps in the KB Required Data CloudBees License Certificate Expiration