Getting started with plugin management

7 minute read

Plugins are the building blocks of CloudBees Jenkins-based products. Your environment may have hundreds of plugins that need to be managed.

Plugin management encompasses installing, updating, removing, and disabling plugins. Administrators also need to ensure that plugins are stable and work well with each other.

To get started with plugin management, do the following:

Determining a plugin management strategy

To determine the best plugin management strategy for your organization, review the following questions.

Then, review the Comparison chart for plugin management methods to determine which plugin management method is best for you based on how you answered the questions.

  • What is your operational model?

    • Centralized management for all plugin-related changes on all controllers.

    • One-time default plugin deployment for all controllers, then self-managed afterwards.

    • Allow team/project administrators of each controller to manage and install plugins.

  • Will controllers be restricted on the list of plugins available to them?

  • Do you prefer the definition of plugin list to be in code or via UI?

  • Is the installation of plugins per controller optional or mandatory?

  • Will you keep up to date with the CloudBees Assurance Program compliance?

  • What are the network restrictions and/or corporate policy restrictions on plugins?

  • Do you have any internally developed plugins?

  • What type of controllers will be provisioned?

Comparison chart for plugin management methods

CloudBees offers a variety of methods for managing plugins. The method or methods that you choose to use will vary depending on your company’s needs and environment. CloudBees recommends that you work with CloudBees Professional Services to determine the best method for your situation.

Table 1. Plugin management options
Option Description Benefits

CloudBees Assurance Program (CAP)

This program, which is designed and maintained by CloudBees, tests plugins, plugin versions, and plugin dependencies to determine their stability.

You don’t have to spend time figuring out which versions of plugins work well together. Upgrades have reduced risk, as many plugins are verified together.

Beekeeper Upgrade Assistant (Beekeeper)

The user interface for CAP. It provides a centralized view of the monitored Jenkins plugins, recommended actions, and configuration options.

Beekeeper allows automatic upgrades of plugins and automatic downgrades of plugins. Beekeeper will report when the instance is out of compliance and it will keep plugins up-to-date with versions recommended by CAP. This may mean upgrading a plugin or even downgrading a plugin.

Configuration as Code

CasC simplifies the management of a CloudBees CI cluster by capturing the configuration of CloudBees CI controllers in human-readable declarative configuration files that can then be applied to a controller in a reproducible way.

Plugins are managed using two configuration files, plugins.yaml and plugin-catalog.yaml. Plugins are installed automatically upon boot or restart of a controller, and upon a hot reload on the controller. Plugins listed in the CasC bundle are not optional; they are installed automatically every time.

This option allows for plugins to be defined in code and automates their installation on restart or retry. With CasC, you add plugins to a bundle and configure settings for plugins through a bundle.

Plugin catalog

If you need to install non-CloudBees Assurance Program plugins, such as plugins that are unknown to CloudBees (perhaps developed internally within your organization) or older versions of plugins, you can configure a plugin catalog.

Note that plugin catalogs can also be used to assist with managing plugins in an air-gapped environment. Unfortunately, as it does not process dependencies, it requires a lot of work to configure correctly.

A plugin catalog widens the acceptable scope of plugins beyond those defined by the CloudBees Assurance Program. This scope includes the ability to specify plugin dependency rules and acceptable version ranges for these plugins.

Your plugin catalog can also specify a Maven 2 artifact repository from which to download plugins.

Cluster operations

Cluster operations is a facility to perform maintenance operations on various items in the operations center, such as client controllers and update centers. Different operations are applicable to various items such as performing backups or restarts on client controllers, or upgrade/install plugins in update centers, etc.

Allows an administrator to upgrade, install, enable, or disable plugins on one or more controllers at the same time. This makes it easy to affect multiple controllers and enforce plugin changes across the whole environment.

Manage Plugins UI

The Manage Plugins page is available to all Jenkins administrators. Plugins can be installed, uninstalled, and updated via the UI. The Advanced tab lets administrators install custom plugins, or plugins that are not available from the update center or the plugin catalog.

This is the simplest and most common way of installing plugins.

Jenkins CLI

The Jenkins CLI has commands that can perform plugin installations, enable, disable, and list plugins. This CLI command can be performed by a script and must be triggered on each controller.

From the CLI, plugins can be installed by name (via update center) and by a link to a plugin (via URL or file).

Team controller recipes

Team controller recipes contain plugins and pluginCatalog as configurable parameters. The defined plugins are installed when team controllers are provisioned.

Team controller recipes are not compatible with Configuration as Code. If you try to use both, only the CasC configuration is applied.

Team controller recipes apply only to environments that use team controllers. A recipe provides a base default team controller installation that teams can build upon.

Update Center

The Update Center allows Jenkins administrators to host their own Jenkins Update Center for the Jenkins instances they administer.

This option provides Jenkins administrators with the ability to restrict the plugins that are available and to host their own custom plugins.

This option is not recommended and is no longer being developed. Use this option only if you have an air-gapped environment and need a CloudBees solution.

Example plugin management architectures

Operations center with Update Center

The operations center can be configured with the default public Update Center, which uses public update sites as the upstream sources. The Jenkins controllers can use the Update Center to download plugins. The operations center and controllers use different Update Centers for the appropriate plugins list. This is the default and recommended approach unless there is a constraint.

Operations center with Update Center

Update Center router via proxy

The operations center can be configured with the default or custom Update Center, which uses public update sites as the upstream sources. The operations center routes via a proxy to reach the public update sites. The controllers use the Update Center to download plugins or they can also route via the proxy to the public update sites.

Update Center router via proxy

The managed controller on the left is using the Update Center hosted on the operations center instance and is downloading plugins from there.

The managed controller on the right is using the public Update Center and is routing via the proxy to download plugins.

When using a proxy with defined allowlists, be aware of redirects when downloading plugins.

Operations center with custom Update Center

The operations center can be configured with a custom Update Center, which uses public update sites as the upstream sources. Custom Update Centers allow the Update Center to be configured on the operations center instance. This allows more control over which plugins are available to the controller. The administrator can control this from the operations center.

Operations Center with custom Update Center

The controllers will download their plugins from the Update Center, which in this case is hosted on the operations center.

Custom Update Centers do not perform plugin dependency resolution. The administrator must understand and make available the full dependency chain of plugins. This can be a large overhead of effort.

In air-gapped environments with no internet or proxy access, every plugin and dependency must be added manually.

Plugin catalog with proxied repository

The plugin catalog is configured on the operations center and controllers reference plugins on the internal company artifact repository. The internal artifact repository proxies to the public repository (CloudBees Maven Repo) to mirror artifacts.

Plugin catalog with proxied repository

The CloudBees maven repository ( is represented as the public repository.

The plugin catalog must be complemented by one of the Update Center architectures because CloudBees Assurance Program plugins cannot be provided using the plugin catalog.

The negatives of plugin catalog:

  • Plugin catalog requires definition of plugins and all its dependencies, and management of this configuration.

  • Administrators who create the definition file have to find all required dependencies and version dependencies.

  • It does not identify plugins out of CloudBees Assurance Program compliance.

  • The controllers will download the plugins from the source location; they cannot be distributed by the operations center.

Configuration as Code

Configuration as Code (CasC) lists the CloudBees Assurance Program plugins in plugins.yaml. These plugins are all bundles inside of the controller and are provisioned based on the YAML definition. Non-CloudBees Assurance Program plugins are listed in plugin-catalog.yaml; these are downloaded from the standard Update Centers or from a specified location provided in the definition.

Configuration as Code

CasC bundles all the CloudBees Assurance Program plugins into the controller and makes available those plugins that have been chosen in the plugins.yaml file. This requires no internet connectivity to download plugins, although updates require connectivity using one of the Update Center architectures.

The non-CloudBees Assurance Program plugins defined in plugin-catalog.yaml are downloaded from the standard Update Centers, unless a location is provided from which it can download from a URL. This will not follow redirects.

Team controller recipes

Team controller recipes define the CloudBees Assurance Program plugins in the plugins parameter. These plugins are downloaded from the Update Center. Non-CloudBees Assurance Program plugins are defined in the pluginCatalog parameter and these plugins are downloaded from public repositories or defined URLs. This architecture is a combination of Beekeeper Plugin Catalog architecture and an Update Center architecture. It can be altered for use via a proxy or using internal repositories.

Team controller recipes

Update Center with controller in DMZ

An “OPS” managed controller launched into the DMZ network with custom Update Centers installed and configured to use the public CloudBees update site or another public update site. operations center and controllers point to this Update Center.

Update Center with controller in DMZ

Air-gapped network with Update Center

In an air-gapped network, an Update Center can be used to distribute plugins to the controllers. All plugins must be uploaded manually or using a scripted process to the Update Center.

Plugins must be brought into the air-gapped network using corporate policy and require approval to do so.

Air-gapped network with Update Center

Air-gapped network with plugin files

In an air-gapped network, plugin files can be stored internally and distributed to the file systems for each controller, either manually or using a scripted process.

Caveat: Plugins applied this way do not guarantee compatibility or dependency management.

Air-gapped network with plugin files
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.