Preparing for the new CloudBees License Certificate

Article ID:360041962612
6 minute readKnowledge base
This article references an issue that affects a product version that is no longer supported. Please verify the version listed in the article applies to your situation. If unsure, please submit a support ticket at: https://support.cloudbees.com/.

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

CloudBees product version 2.176.1.4 or later

Follow the instructions in Global Overview to install the new license generated by the new certificate.

Your software is already compatible with the new certificate, so applying the new license is the only action you have to take before June 22, 2020.

CloudBees product version 2.164 or earlier

Perform all of the following actions in the order listed:

  1. Follow the article on Upgrading for the new CloudBees License Certificate

  2. Follow the instructions in Global Overview to install the new license generated by the new certificate.

Be sure to complete all of the steps listed above before June 22, 2020.

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 controllers in addition to the Operations Center itself.

This script does not make any changes to your controller 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 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. 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 controllers...
 \[controller1\]
 \[controller2\]
 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.
 controller1 - cloudbees-license plugin 9.24.1 is installed. This instance is ready to install the new license.
 controller2 - 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 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 controller 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:

Method

Details

Run the Apply License script

This is the recommended method. The script automatically retrieves the new license from the CloudBees server.

Manually request and apply the license

This method is available for customers who do not have internet access or who prefer not to use the script.

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 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. Once the script has been run, it should print a message saying that the new license has been successfully applied.

Note that connected controllers 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 controller.

  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 controller 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 controllers 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 controllers 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>.

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