Managing plugins with the CloudBees Update Center

9 minute read

The CloudBees Update Center plugin gives a Jenkins administrator the ability to host their own Update Center for the Jenkins instance(s) that they administer. This Update Center will provide the Jenkins Administrator with the ability to both restrict the plugins available and host their own custom plugins.

Starting on 19 October 2021 (18:31:36 GMT), you may see an error message on the Plugin Management page on your CloudBees CI instances. This error has no impact on the operational status of your instance; all of your builds will run as usual. However, this could impact you when creating new controllers for both online and air-gapped environments.

Release 2.303.2.6 enables plugin installation and updates for instances in air-gapped environments, removes the error from the Plugin Management page, and corrects plugin installation during new controller provisioning for online and air-gapped environments.

Please refer to the following KB article for more information and workarounds:

Creating an Update Center

Update centers can be created just like regular jobs. Go to New Job, enter a name for the Update Center and choose Update Center as the job type.

There are a number of options that you can configure for the update center:

  • Plugin Versioning Strategy - this strategy is applied whenever a new plugin (i.e. one where there are no existing versions installed) is first installed in the Update Center. There are two strategies. The first will not publish any version of the plugin until the user explicitly selects a version to publish. The second will always publish the newest version of the plugin that is installed in the Update Center. See Version number rules for a description of how version numbers are compared by Jenkins.

  • Signature provider - Jenkins versions from 1.424 onwards expect that the Update Center metadata is signed by a known certificate. Select the certification signature provider to use for signing the Update Center metadata.

  • Upstream sources - by selecting upstream sources to pull updates from you can track other Update Centers and installing plugin versions is easier as the plugins do not have to be manually downloaded onto your computer and then uploaded into the Update Center.

  • Maintenance tasks - allows control of periodic tasks such as downloading new versions of plugins installed in the Update Center, or installing new plugins from the upstream sources into the Update Center.

Figure 1. Configuring an Update Center
Figure 1. Configuring an Update Center

Using the Update Center

The main Update Center screen consists of a number of tabs.

Info tab

Figure 2. Main Update Center informations screen
Figure 2. Main Update Center informations screen

This screen displays some basic information about the Update Center:

  • How much disk space is being used by the Update Center

  • What the Update Center’s URL is

There are only two occasions when it is appropriate to use the installer plugin:

  • You need to configure operations center itself to use a self-hosted Update Center.

  • You need to make plugins available to a Jenkins instance that cannot access any external Update Centers in order to install the operations center plugins required to join it into operations center using the converter plugin.

    This requires a full understanding of the plugin requirements and it is usually a better option to use a CloudBees product based on Jenkins instead.

Once a Jenkins instance is joined to the operations center cluster you should use the Specify Update Center for Controller option to push the Update Center configuration to the controller.

uc connected master property
Figure 3. The recommended way to configure a controller connected to operations center to use a custom Update Center.

The plugin that the link downloads will access the Update Center via the URL that the link corresponds to. Thus it is best to access the link from the machine that the plugin will be installed on in order to ensure that the correct (from that machine) URL for accessing the Update Center is used.

The plugin that the link downloads will ensure that the matching certificate checks are performed, i.e. if the Update Center is using a Self-Signed Certificate to sign the update-center.json file, the plugin will include the corresponding certificate chain in order to ensure the `update-center.json’s authenticity.

Similarly, if the Update Center is not using any Certificates to sign the update-center.json then the plugin will instruct Jenkins not to require a signed update-center.json for that specific Update Center, irrespective of the Jenkins instance’s global certificate requirements.

There are two ways to install the plugin in a Jenkins instance:

  • Using the Web Interface

    1. From the Update Center, download the Update center installer plugin. (Ideally downloading it via a browser running on the same machine as the Jenkins instance that will be using the Update Center as its Update Center)

    2. Go to the Jenkins instance’s root page.

    3. If the Jenkins instance has security enabled, login as a user with has the Overall | Administerpermission.

    4. Select the Manage Jenkins link on the left-hand side of the screen.

    5. Select the Manage Plugins link.

    6. On the Advanced tab use the Upload Plugin option to upload the plugin.

      uc plugin install
      Figure 4. Uploading the Update Center Installer Plugin into a Jenkins instance
    7. Check the Installed tab. If the Jenkins instance says that it requires a restart, then restart the Jenkins instance.

  • Using the Command Line Interface

    1. From the Update Center, download the Update center installer plugin. (Ideally you should download it via a browser running on the same machine as the Jenkins instance that will be using the Update Center as its Update Center.)

    2. Stop the Jenkins instance.

    3. Move (or copy) the downloaded plugin into the $JENKINS_HOME/plugins/ directory

    4. Start the Jenkins instance.

Core tab

uc core install
Figure 5. The Core tab of the Update Center screen

This screen provides details of Jenkins distributions.

The Promoted Version section lists all the versions of Jenkins that are installed in the Update Center and allows for one specific version to be advertised via the Update Center’s update-center.json

The Upstream Versions section lists any versions of Jenkins, coming from the Update Center’s upstream sources, that have not been installed in the Update Center

Only versions of Jenkins which have been installed in the Update Center can be advertised via the Update Center’s update-center.json. This is to ensure that the Update Center can continue to serve even if the upstream source is off-line.

To install a version of Jenkins from the upstream sources, just click on the corresponding Store button and the download will be added to the download queue.

uc core downloading
Figure 6. A core distribution being downloaded into the Update Center

Plugins tab

Figure 7. The Plugins tab of the Update Center screen
Figure 7. The Plugins tab of the Update Center screen

This screen provides details of all the Plugins known to this Update Center, i.e. all the plugins advertised by the Update Center’s upstream sources as well as all the plugins installed in the Update Center.

Clicking on a Plugin’s name will display the Plugin information screen

uc plugin install
Figure 8. The plugins details screen when no version of a plugin is installed in the Update Center
uc plugin config
Figure 9. The plugins details screen with a version of the plugin installed in the Update Center

The Promoted Version section lists all the versions of the plugin that are installed in the Update Center and allows for one specific version to be advertised via the Update Center’s update-center.json

The Upstream Versions section lists any versions of the plugin, coming from the Update Center’s upstream sources, that have not been installed in the Update Center

Only versions of plugins which have been installed in the Update Center can be advertised via the Update Center’s update-center.json. This is to ensure that the Update Center can continue to serve even if the upstream source is off-line.

To install a version of a plugin from the upstream sources, just click on the corresponding Store button and the download will be added to the download queue.

Tools tab

Figure 10. The Tools tab of the Update Center screen
Figure 10. The Tools tab of the Update Center screen

This screen provides details of all the Tool installers known to this Update Center, i.e. all the tool installers advertised by the update center’s upstream sources.

Clicking on a Tool installer’s name will display the list of versions of the Tool installer that are available.

The Update Center plugin does not currently support hosting private versions of Tool installers.

Upload Core tab

uc upload core
Figure 11. The Upload Core tab of the Update Center screen

This screen provides for manual uploading of custom distributions of Jenkins into the Update Center.

Upload Plugin tab

uc upload plugin
Figure 12. The Upload Plugin tab of the Update Center screen

This screen provides for manual uploading of custom plugins into the Update Center.

Maintenance

There are two maintenance tasks available:

  • Pull new versions

  • Pull everything

Pull new versions

This maintenance task is used when you just want to follow a small set of plugins. When this task runs it performs the following steps:

  1. Checks all the upstream sources for any versions of the core Jenkins distribution that are not installed in the Update Center. If any versions are found, they will be queued for download.

    If Core is set to track the Latest version and one of the downloaded versions is newer than the current latest version, then this will result in the newer version being immediately published once the download has been completed. (See Version number rules for a description of how version numbers are compared by Jenkins.)

    If Core is set to either None or a specific version, then no change to the published version will take place.

  2. Checks all the upstream sources for any versions of each plugin with at least one version currently installed in the Update Center. If any versions are found, they will be queued for download.

    If any of the plugins are set to set to track the Latest version and one of the downloaded versions is newer than the current latest version, then this will result in the newer version being immediately published once the download has been completed. (See Version number rules for a description of how version numbers are compared by Jenkins.)

    If a plugin is set to either None or a specific version, then no change to the published version will take place.

Pull everything

This maintenance task is used when you want to track everything in the Update Center’s upstream sources. When this task runs it performs the following steps:

  1. Checks all the upstream sources for any versions of the core Jenkins distribution that are not installed in the Update Center. If any versions are found, they will be queued for download.

    If Core is set to track the Latest version and one of the downloaded versions is newer than the current latest version, then this will result in the newer version being immediately published once the download has been completed. (See Version number rules for a description of how version numbers are compared by Jenkins.)

    If Core is set to either None or a specific version, then no change to the published version will take place.

  2. Checks all the upstream sources for any versions of all plugins published by the upstream source. If any versions are found, they will be queued for download.

    If any of the plugins are set to track the Latest version and one of the downloaded versions is newer than the current latest version, then this will result in the newer version being immediately published once the download has been completed. (See Version number rules for a description of how version numbers are compared by Jenkins.)

    If a plugin is set to either None or a specific version, then no change to the published version will take place.

Reference Information

Version number rules

Jenkins compares plugin versions using the following strategy:

  • Each version number is split into segments separated by '-' and '.' characters.

  • Starting with the first segment of each version number, segments are compared until a difference is encountered.

  • If both segments are numeric, they are compared as numbers, otherwise they are compared as strings. There are a couple of special qualifier strings that get special treatment, for example if the string starts with 'a', 'b' or 'm' and the remainder of the string is a number, then those segments will be compared based as if the letter was replaced by 'alpha-', 'beta-' or 'milestone-' respectively. Also the qualifiers: 'snapshot'; 'alpha'; 'beta'; 'milestone'; 'rc' or 'cr'; '' or 'final' or 'ga'; and 'sp' will be sorted according to that sequence.

  • Where the values of a segment are the same, if the preceding separator was '.' then that comes before '-'.

Other tasks

Removing a custom Update Center as an updates source from a Jenkins instance

If you want to remove a custom Update Center as an updates source you would have to: * disable it in the client controller configuration page from the operations center if you have pushed the configuration from there (this is the suggested and preferred way) * uninstall or disable the custom Update Center installer plugin and restart your Jenkins instance if instead you have configured the custom Update Center by installing the custom Update Center installer plugin on the client controller.

The list of Update Centers will not be modified on disk as a result of the change, but the custom update center will not be loaded into the list of Update Centers and you will see the following

WARNING: Failed to resolve class com.thoughtworks.xstream.mapper.CannotResolveClassException: custom

in your logs until the list of Update Centers is re-saved to disk.

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.