Getting started with plugin management

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

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

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

  • Will Masters 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 Master 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 Masters 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) for Masters

CasC for Masters simplifies the management of a CloudBees CI cluster by capturing the configuration of CloudBees CI masters in human-readable declarative configuration files that can then be applied to a master 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 master, and upon a hot reload on the master. 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 operation jobs

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

Allows an administrator to upgrade, install, enable, or disable plugins on one or more Masters at the same time. This makes it easy to affect multiple Masters 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 will have to be triggered on each master.

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

Team Master recipes

Team Master recipes contain plugins and pluginCatalog as configurable parameters. The defined plugins are installed when Team Masters are provisioned.

NOTE: Team Master recipes are not compatible with CasC for masters. If you try to use both, only the CasC configuration is applied.

Team Master recipes apply only to environments that use Team Masters. A recipe provides a base default Team Master 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.

WARNING: 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 Masters can use the Update Center to download plugins. The Operations Center and Masters 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 Masters 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 Master on the left is using the Update Center hosted on the Operations Center instance and is downloading plugins from there.

The Managed Master 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 Master. The administrator can control this from the Operations Center.

Operations Center with custom Update Center

The Masters 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 Masters 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 Masters 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 Master 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 Master 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 Master recipes

Team Master 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 Master recipes

Update Center with Master in DMZ

An “OPS” Managed Master 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 Masters point to this Update Center.

Update Center with Master in DMZ

Air-gapped network with Update Center

In an air-gapped network, an Update Center can be used to distribute plugins to the Masters. 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 Master, 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