Upgrading plugins with Beekeeper Upgrade Assistant

6 minute read

CloudBees offers the Beekeeper Upgrade Assistant (Beekeeper), which is the user interface that administrators can use to manage plugin versions and enforce compliance with the CloudBees Assurance Program’s recommended sets of plugins and versions.

When the Beekeeper Upgrade Assistant plugin is installed, the Beekeeper Upgrade Assistant option appears on the Manage Jenkins screen under System Configuration.

Beekeeper regularly evaluates the state of the instance to ensure compliance with the CloudBees Assurance Program and alerts administrators when plugin upgrades are available.

Beekeeper alert for an available upgrade
Figure 1. Upgrade message from header

Before any upgrade, CloudBees recommends creating a backup of the instance in case of an unexpected failure during the upgrade process.

Once an upgrade is installed, the recommended plugins that the CloudBees Assurance Program enforces are automatically changed, so the report offered by the Beekeeper plugin may automatically change from compliant to non-compliant. This is normal because restarting the instance is required for the upgrade to complete. After the restart, the Beekeeper report should return to its previous state. However, note that recurring non-compliance issues, such as installation of a plugin that is not in the CloudBees Assurance Program, continue to appear on the report.

If an upgrade fails, Beekeeper notifies the administrator and allows the upgrade to be canceled.

Viewing the Beekeeper Upgrade Assistant

To view the Beekeeper Upgrade Assistant:

  1. In your CloudBees product, select Manage Jenkins  Beekeeper Upgrade Assistant.

    Beekeeper Upgrade Assistant
    Figure 2. Beekeeper Upgrade Assistant

Configuring options for Beekeeper Upgrade Assistant

In the Beekeeper Upgrade Assistant, administrators can enroll instances in the CloudBees Assurance Program, set up automatic upgrades or downgrades of plugins to keep verified plugins up to date with the versions that the CloudBees Assurance Program recommends, and configure options for security updates.

To configure options for Beekeeper Upgrade Assistant:

  1. In your CloudBees product, select Manage Jenkins  Beekeeper Upgrade Assistant  CAP Configuration.

  2. Select the configuration options that you want to use. Review the table below for details about each option.

  3. Select Save.

  4. Restart the instance to allow Beekeeper to perform any required plugin upgrades.

    Table 1. Beekeeper configuration options
    Option Description

    Enroll this instance in the CloudBees Assurance Program

    Selecting Enroll this instance in the CloudBees Assurance Program causes the following to occur:

    • The Beekeeper plugin monitors the instance’s installed plugin list and checks it against the monitored plugin list. This means that for each plugin in the list that is installed, if the installed plugin version is different than the specified version, a warning is generated.

    • The update center configuration is set to a specific CloudBees-provided update center that, for the set of monitored plugins, offers only the version specified in the list and filters the rest of the available plugins so that they are compatible (dependency-wise) with the plugins and versions in the monitored list.

    • The Update and Available views in the Plugin Manager are also filtered in the same way, in case additional update centers are configured.

    If Enroll this instance in the CloudBees Assurance Program is not selected, the following occurs:

    • No monitoring is performed.

    • The update center is configured to a generic update center that still points to the CloudBees Update Center service and provides the latest version of the plugins.

    • No local filtering is performed for the Updates and Available views in the Plugin Manager.

    Allow automatic upgrades of plugins on restart

    CloudBees does not recommend that you disable the automatic plugin upgrades as your plugin upgrades may fail and the controller may not restart.

    Enabling automatic plugin upgrades can help administrators automatically keep their verified plugins up to date with the versions recommended by the CloudBees Assurance Program. The Allow automatic upgrades of plugins on restart option can only be selected if the Enroll this instance in the CloudBees Assurance Program option is selected.

    When the automatic upgrade option is enabled, Beekeeper tries to upgrade every plugin in the list of monitored plugins whenever the instance is restarted. If an upgrade requires the installation of dependencies, the dependencies are installed before the plugin is upgraded.

    Automatic upgrades fail in the following situations:

    • Any required dependency fails to install or upgrade.

    • The system is unable to install the target version of the plugin in the appropriate location inside the $JENKINS_HOME folder.

    If automatic upgrades are not enabled, Beekeeper indicates when your instance becomes out of compliance with the verified plugins in the CloudBees Assurance Program. You can then manually upgrade the plugins that are out of compliance.

    Some plugins (internally those in bootstrap and possibly their optional installed dependencies) are upgraded or reverted on an upgrade as they are required for the plugin to function.

    Allow automatic downgrades of plugins on restart

    You can enable Beekeeper to automatically downgrade any installed plugins that exceed the versions that the CloudBees Assurance Program recommends. When the automatic downgrade option is enabled, Beekeeper tries to downgrade every plugin in the list of monitored plugins whenever the instance is restarted. The Allow automatic downgrades of plugins on restart option can only be selected if the Enroll this instance in the CloudBees Assurance Program option is selected.

    While this option affects only the plugins considered to be verified and part of the CloudBees Assurance Program, using this option may cause unintended side effects on stability if the instance has been taking advantage of features and configurations provided by more recent versions of those plugins.

    CloudBees does not recommend that you enable automatic plugin downgrades. If you choose to use this option, you should back up your instance before you enable it.

    Automatic downgrades fail in the following situations:

    • Other plugins in the system depend on the currently installed version and this dependency is not satisfied by the target version.

    • The system is unable to install the target version of the plugin in the appropriate location inside the $JENKINS_HOME folder.

    Notify when security warnings affecting the core are detected

    Selecting this option enables Beekeeper to notify you if security warnings related to the Jenkins core version that your CloudBees Jenkins-based product is based on are detected. For more information about security warnings, see Understanding Beekeeper security warnings.

    Notify when security warnings affecting plugins are detected

    Selecting this option enables Beekeeper to notify you if security warnings related to plugins are detected. For more information about security warnings, see Understanding Beekeeper security warnings.

Automated incremental upgrades with Beekeeper

The CloudBees Assurance Program can provide incremental upgrades, which include a subset of functionality delivered prior to the full product release. For example, incremental upgrades may deliver plugin security fixes or important new features that can’t wait until the next full product release.

Incremental upgrades appear in Beekeeper with a message that a new revision is available. The upgrade page shows the current and offered revisions, as well as a simulation of the changes.

Depending on the plugins you have installed, a change may not be needed in the running instance. CloudBees recommends that you choose the upgrade even in those cases so that Beekeeper uses the upgraded configuration.

Incremental upgrades
Figure 3. Incremental upgrades

If you perform an initial installation of a version for which an incremental upgrade is available and the instance is connected to CloudBees Update Center, you have the option to apply the upgrade from the setup wizard. If you decide to install the incremental upgrade from the setup wizard, depending on the affected plugins, an additional restart may be required at the end of the installation process. If you decide to skip the upgrade in the setup wizard, it is available from the Beekeeper Upgrade Assistant for you to install when it’s convenient.

If you need to automatically skip this behavior, set the system property cb.BeekeeperProp.disableIncrementalWizard to true.

Beekeeper system properties

Property Default Description

cb.BeekeeperProp.noFullUpgrade

false

Set to true to not check for full upgrades. Does not disable checks for security fixes to currently installed plugins, even if the security fixes for those currently installed plugins require a full upgrade. An older installation that includes a plugin with a known security issue will be shown as a Beekeeper warning. The solution to that warning may require a full upgrade, but with noFullUpgrade=true, that upgrade will not be included in the warnings

cb.BeekeeperProp.autoInstallIncremental

false

Set to true to install incremental upgrades automatically at startup

cb.BeekeeperProp.disableIncrementalWizard

false

Disable checking for incremental releases during the setup wizard

com.cloudbees.jenkins.cjp.installmanager.CJPPluginManager.allRequired

false

If true, every plugin in the envelope will be considered required when CloudBees Assurance Program is enabled

com.cloudbees.jenkins.cjp.installmanager.CJPPluginManager.suggestedRequired

false

If true, all suggested plugins (as defined in the setup wizard) in the envelope will be considered required when CloudBees Assurance Program is enabled.

In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.