Beekeeper plugin exceptions provide a way to fix urgent bugs or security issues related to plugins by upgrading to a version of a plugin that is not yet available in the CloudBees Assurance Program (CAP).
Beekeeper plugin exceptions are intended to be temporary and are not recommended because they may cause unintended consequences. Therefore, Beekeeper plugin exceptions are disabled by default and only users with Configure Controller permissions can allow exceptions. For details, see Important considerations for using Beekeeper plugin exceptions. If you enable Beekeeper plugin exceptions, return to the approved plugin version in CloudBees Assurance Program as soon as possible.
| Only plugin upgrades are allowed. You cannot downgrade plugin versions using an exception. |
Important considerations for using Beekeeper plugin exceptions
By allowing a plugin exception, you no longer have a verified configuration.
Ensure you understand the following issues before you allow a plugin exception:
-
Plugins may not work together as expected.
-
You may experience instability in your environment.
-
Your system may experience performance issues.
-
You do not receive full support from CloudBees as you do with a verified plugin.
Prerequisites for using Beekeeper plugin exceptions
The following plugins must be installed to enable Beekeeper plugin exceptions:
-
CloudBees operations center Client plugin version 2.235.0.9 or later installed on the controller
-
CloudBees operations center Server plugin version 2.235.0.11 or later installed on the operations center
-
CloudBees Assurance plugin version 2.138.0.17 or later installed on both the controller and the operations center
In addition, you must have Configure Controller permissions.
Setting up Beekeeper plugin exceptions
| Be sure to read the important considerations for using Beekeeper plugin exceptions before you start this procedure. |
To set up Beekeeper plugin exceptions:
-
Add Beekeeper plugin exceptions to a plugin
plugin-catalog-file.jsonfile. See Defining a plugin catalog for details about how to create a plugin catalog.-
Use the following example format for exceptions in the plugin catalog:
{ ..., "beekeeperExceptions" : { "support-core": { "version" : "2.70" } } } -
The following example plugin catalog shows a Beekeeper plugin exception and an inclusion for another plugin:
{ "type" : "plugin-catalog", "version" : "1", "name" : "override", "displayName" : "override", "configurations" : [ { "description" : "override", "includePlugins" : { "greenballs": { "version" : "1.14" } }, "beekeeperExceptions" : { "support-core": { "version" : "2.70" } } } ] }
-
-
Ensure the plugin catalog is installed on operations center. See Adding a plugin catalog
-
From the operations center, click the arrow next to the controller for which you want to allow an exception.
-
Select Configure.
Figure 1. Allow exceptions -
Under Plugin Catalog, select Allow exceptions.
-
Select Specify a plugin catalog for this controller.
-
In Catalog, select the name of the plugin catalog that contains the exception.
-
Select Check Validity. Ensure that "The catalog is compatible with the controller" is returned.
-
Select Save.
Viewing Beekeeper plugin exceptions
Exceptions appear on the Beekeeper Plugin Exceptions screen, where you can find the plugin ID, the version number that’s in the CloudBees Assurance Program, the version number of the exception, and the SHA1.
To view Beekeeper plugin exceptions:
-
From the controller, select Manage Jenkins > Beekeeper Upgrade Assistant.
-
On the left, select Beekeeper Plugin Exceptions.
Figure 2. Beekeeper Plugin Exceptions screen
Removing a Beekeeper plugin exception
CloudBees recommends removing Beekeeper plugin exceptions as soon as you are done with them to ensure that you are using a verified version of a plugin.
You can do one of the following:
-
Remove the exception and revert to the version in CloudBees Assurance Program.
-
Remove the exception and upgrade the controller to a version equal to or newer than the exception.
To remove the exception and revert to the version in CloudBees Assurance Program:
-
Go to Manage Jenkins > Manage Plugins.
-
On the Installed tab, select Downgrade next to the plugin name to revert to the plugin version that is verified in CloudBees Assurance Program.
-
Remove the exception from the plugin catalog.
-
From the operations center, click the arrow next to the controller from which you want to remove the exception.
-
Select Configure.
-
Uncheck Allow exceptions.
To remove the exception and upgrade the controller to a version equal to or newer than the exception:
-
Remove the exception from the plugin catalog.
-
Apply the updated plugin catalog to the controller.
-
From the operations center, click the arrow next to the controller from which you want to remove the exception.
-
Select Configure.
-
Uncheck Allow exceptions.
-
From the controller, select Manage Jenkins > Beekeeper Upgrade Assistant.
-
On the left, select CAP Configuration.
-
Verify Allow automatic upgrades of plugins on restart is selected.
-
Click Save.
-
Restart the instance.
Troubleshooting Beekeeper plugin exceptions
-
I received an error message that Beekeeper plugin exceptions are not supported. What should I do?
The latest version of both the CloudBees operations center Client plugin and the CloudBees operations center Server plugin is required to use Beekeeper plugin exceptions. Upgrade those two plugins, and then try again.
-
I received an error message that Beekeeper plugin exceptions are unknown. How do I resolve that?
The controller is offline, so the exceptions cannot be validated. Ensure the controller is online, and then try again.
-
I specified a plugin catalog for a controller and received an error message, “The controller is not allowed to have Beekeeper Plugin Exceptions”. Why does this error appear?
You must select the Allow exceptions checkbox in addition to specifying a plugin catalog.
Figure 3. Allow exceptions error