What do the options in Beekeeper Upgrade Assistant mean?

Article ID:227569487
5 minute readKnowledge base

Issue

  • What do the options in the Beekeeper Upgrade Assistant mean?

Environment

Resolution

There are five options in the Beekeeper Upgrade Assistant View:

  • Enroll this instance in the CloudBees Assurance Program

  • Allow automatic upgrades of plugins on restart

  • Allow automatic downgrades of plugins on restart

  • Notify when security warnings affecting the core are detected

  • Notify when security warnings affecting plugins are detected

The second and third options only have any effect if the first one is checked.

It is recommended to always have all options enabled except the Allow automatic downgrades of plugins on restart, which should only be enabled after CloudBees support advises you to enable it.

Enroll this instance in the CloudBees Assurance Program

Having this option enabled has the following consequences in the system:

  • The Beekeeper plugin monitors the instance installed plugin list and checks it against the monitored plugin list (included below). This means that for each plugin in this list that is installed, if the installed plugin version is different than the specified one, a warning is generated.

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

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

The list of plugins monitored by the Beekeeper plugin are the ones included in the release notes for the controller and operations center at:

These lists contain the plugin ids, their versions and whether they are required or optional.

If the option is disabled:

  • No monitoring is performed.

  • The Update Center is configured to one that provides the latest version of the plugins.

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

  • Plugin upgrades can break product features, or cause your instance to fail to start after reboot

If you use CasC to handle your instances, you can activate CAP as well as follows:

beekeeper:
  enabled: true
▼
Remarks

  • Changing the value of this configuration option involves a reconfiguration of the Update Centers. In the current version, either waiting for a refresh of metadata or a manual one ("Check Now" button in the "Advanced" tab of the plugin manager) is needed.

  • If a custom update center (using the CloudBees Update Center plugin) or a CJOC-provided Update Center is configured in the system, the Beekeeper Upgrade Assistant does not install the Update Center configuration described above.

Allow automatic upgrades of plugins on restart

CloudBees recommends automatic plugin upgrades are always enabled to avoid plugin issues and startup failures when upgrading your environment.

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.

If the instance is enrolled in the CloudBees Assurance Program and this option is enabled, in every restart of the instance, for every plugin in the monitored list that is installed in the system in an older version than the one provided in the list the Upgrade Assistant will try to upgrade the plugin.

If your controller is offline, and you’d like to enable automatic plugin upgrades upon restart, you can enable them by running (tested with version 2.414.2.2):

touch $JENKINS_HOME/cb-envelope/upgrade-plugins.enabled
▼

If you use CasC to handle your instances, you can activate Allow automatic upgrades of plugins on restart as well as follows:

beekeeper:
  enabled: true
  [...]
  upgrades:
    [...]
    autoUpgradePlugins: true
▼

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

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.

Downgrading plugins is not supported, and in some cases could cause the plugin to fail to be able to read it’s configuration, so this should only be done based upon the advise of CloudBees support.

If the instance is enrolled in the CloudBees Assurance Program and this option is enabled, in every restart of the instance, for every plugin in the monitored list that is installed in the system in a newer version than the one provided in the list the Upgrade Assistant will try to downgrade the plugin.

As always downgrades are much riskier than upgrades, this option should be used with great caution and in any case backup should always be performed before.

The downgrade will fail if:

  • There are other plugins in the system that depends 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.

If you use CasC to handle your instances, you can activate Allow automatic downgrades of plugins on restart as well as follows:

beekeeper:
  enabled: true
  [...]
  upgrades:
    [...]
    autoDowngradePlugins: true
▼

Notify when security warnings affecting the core are detected

When this option is enabled, the Beekeeper Upgrade Assistant will notify if any security warning affecting the core is detected making use of the administrative monitors. Please be aware, that the administrative monitor should be disabled in case of desiring to avoid completely the notifications of security vulnerabilities.

Notify when security warnings affecting plugins are detected

When this option is enabled, the Beekeeper Upgrade Assistant will notify if any security warning affecting the installed plugins is detected making use of the administrative monitors. Please be aware, that the administrative monitor should be disabled in case of desiring to avoid completely the notifications of security vulnerabilities.

Tested product/plugin versions