Beekeeper plugin exceptions

Beekeeper plugin exceptions is a Preview feature.
Preview

A Preview feature:

  • Has not undergone end-to-end testing with CloudBees products

  • Is provided without service-level agreements (SLA) and therefore does not include CloudBees' commitment on functionality or performance

  • May impact other stable areas of the product when used

  • May have limited documentation

  • May not be feature complete during the Preview period

  • May graduate from preview state to fully supported or be removed from the product

  • May introduce incompatible, backward-breaking changes that could revoke the ability to upgrade

Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

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.

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 Master 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 master

  • 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 master and the Operations Center

In addition, you must have Configure Master 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:

  1. Add Beekeeper plugin exceptions to a plugin catalog.yaml file. 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"
                       }
                   }
               }
           ]
        }
  2. Ensure the plugin catalog is installed on Operations Center. See Adding a plugin catalog

  3. From the Operations Center, click the arrow next to the master for which you want to allow an exception.

  4. Select Configure.

    allow exceptions
    Figure 1. Allow exceptions
  5. Under Plugin Catalog, select Allow exceptions.

  6. Select Specify a plugin catalog for this master.

  7. In Catalog, select the name of the plugin catalog that contains the exception.

  8. Click Check Validity. Ensure that "The catalog is compatible with the master" is returned.

  9. Click 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:

  1. From the master, select Manage Jenkins > Beekeeper Upgrade Assistant.

  2. On the left, select Beekeeper Plugin Exceptions.

    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 master to a version equal to or newer than the exception.

To remove the exception and revert to the version in CloudBees Assurance Program:

  1. Go to Manage Jenkins > Manage Plugins.

  2. On the Installed tab, select Downgrade next to the plugin name to revert to the plugin version that is verified in CloudBees Assurance Program.

  3. Remove the exception from the plugin catalog.

  4. From the Operations Center, click the arrow next to the master from which you want to remove the exception.

  5. Select Configure.

  6. Uncheck Allow exceptions.

To remove the exception and upgrade the master to a version equal to or newer than the exception:

  1. Remove the exception from the plugin catalog.

  2. Apply the updated plugin catalog to the master.

  3. From the Operations Center, click the arrow next to the master from which you want to remove the exception.

  4. Select Configure.

  5. Uncheck Allow exceptions.

  6. From the master, select Manage Jenkins > Beekeeper Upgrade Assistant.

  7. On the left, select CAP Configuration.

  8. Verify Allow automatic upgrades of plugins on restart is selected.

  9. Click Save.

  10. Restart the instance.

Troubleshooting Beekeeper plugin exceptions

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

  2. I received an error message that Beekeeper plugin exceptions are unknown. How do I resolve that?

    The master is offline, so the exceptions cannot be validated. Ensure the master is online, and then try again.

  3. I specified a plugin catalog for a master and received an error message, “The master 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.

    Allow exceptions error
    Figure 3. Allow exceptions error