Shared configurations

5 minute read

Operations center provides a facility to replicate a subset of system configuration information (configuration snippet) to client controllers.

This feature requires the following (or newer) versions of plugins installed in operations center to work:

  • Operations Center Context 1.6.3

  • Operations Center Server 1.6.8

  • Operations Center RBAC 1.6.2

Additionally, each client controller requires Operations Center Context 1.6.3 or newer to receive the configuration.

Creating a configuration snippet replicates that configuration to any client controllers within the same folder hierarchy that have not opted out of receiving shared configuration. This feature is ideal when you have some configuration such as Alerting or E-mail configuration that should be kept in sync on one (or more) client controllers. It is possible to define multiple shared configuration within the same folder as well in any parent folder and the configuration of all of these will be replicated to the client controller.

Creating a shared configuration

To create a shared configuration, review the following:

It is first important to work out which of your client controllers you wish to receive the shared configuration so that you can identify the correct folder(s) to create the shared configuration in.

For example, if you have six client controllers (A,B,C,D,E, and F) and you wish five (A,B,C,D and E) of them to have the same e-mail configuration (for example: SMTP server or Jenkins instance e-mail)yet only three of the client controllers (C,D and E) to have the alerting information you will need to create one item to contain the e-mail configuration that is in a folder that is the parent of all of the client controllers, and one item to hold the Alerting information that is in a folder that contains or is a parent of only C, D and E.

Root
 + Folder One
 |   \
 |    + Client controller A
 |    + Client controller B
 |    + Folder Two
 |      \
 |       + Client controller C
 |       - Client controller D
 |       - Client controller E
 |
 - Client controller F

In the above hierarchy, the Alerting configuration is created in Folder Two and the e-mail configuration is created in Folder One.

To obtain the correct hierarchy, you may have to move the client controllers to different folders.
  1. Once you have identified the correct location for the Shared Configuration, navigate to that folder and choose New Item, provide a name for the configuration, select the type Miscellaneous Configuration Container and then OK.

    The subsequent screen allows you to define the type of configuration snippet.

  2. By selecting Add Snippet and choosing the type of configuration you want to add, you can enter the configuration of the item to replicate. A list of supported snippets is available below.

add snippet screen

Each snippet is configured as it would be in the main Jenkins Configure System page.

As Jenkins consolidates the configuration in the current folder with the configuration in the parent folders, it is important to know the piece of information within each snippet is the key such that configuration can be overwritten in a child folder. This is done to prevent entering the same key twice by accident. In all cases, when a snippet with the same key is defined in multiple places the one in the folder closest to the folder containing the client controller takes precedence.

Table 1. Supported snippet types and their key attribute
Snippet Type Key Attribute Inheritance Behavior

Alerts

Alert title

Snippets with different keys are combined into the configuration.

E-Mail Notification

N/A

As there can be only one email configuration the closest to the client controller takes precedence, and others are ignored.

System message

N/A

As there can be only one system message, the closest to the controller takes precedence.

Tool Installation

Tool Name

Snippets with different keys are combined into the configuration.

If multiple snippets are are defined with the same key in the same Miscellaneous configuration container, or in a different Miscellaneous configuration container within the same Folder — then the snippet used is non-deterministic and, as such, should be avoided.

Understanding snippet types

Using tool installation

The Tool Installation mechanism allows you to specify tool setup procedures in global configurations and then use them in Jenkins jobs. Various Tool Installation types are provided by Jenkins core and plugins: JDK, Maven, Git, and Docker CLI. Large-scale distributed installations may include dozens of complex tool configurations, hence it is recommended to store them in operations center using this snippet.

Configuring tool installation

Each Tool Installation snippet defines one installation of a tool. It is possible to setup multiple Tool Installations. To do this, do the following:

  1. Create a new Tool Installation snippet.

  2. Select a tool type to snippet.

  3. Configure the tool according to the guidelines available in the built-in help on on plugin Wiki pages.

    • Installation names should be unique within one tool type

    • It is possible to set up multiple tool installers for different node labels

snippets tool installer select snippet
Figure 1. Step 1. Selecting the snippet
snippets tool installer select tool
Figure 2. Step 2. Selecting tool to be installed
snippets tool installer config
Figure 3. Step 3. Setting up a tool (JDK from Jenkins Core)
Understanding behavior specifics

The following define function behaviors when using Tool Installer:

Feature Description

Missing Plugins

When a tool is configured in the Miscellaneous Configuration Container or any part of its configuration (for example: Tool Installer) come from a plugin not installed on a client controller, the configuration for that specific tool won’t be propagated to that client controller. If the missing plugin is installed on the attached client controller, a reconnection of the client controller is required in order to make the Tool Installation be propagated to the client controller.

Form Verification

Tool Installation or Tool Installer configuration forms may provide verification for the configuration entries or contain check buttons (for example: Test Connection). In the case of the Shared Configuration Snippet, all these verification handlers will be launched on the operations center instance instead of the client controllers. It means that the verification result may be false-positive or false-negative, because operations center and client controller environments may differ.

It is highly recommended to double-check tool configurations on operations center and on client controllers after making changes.

Reviewing tested tools

The Tool Installation Snippet has been tested with the following tools:

A correct behavior for other Tool Installation types is not guaranteed. If you see any issues with the configuration propagation, please contact the CloudBees Support team.

Configuring tool installation for plugin developers

If your plugins provide their own Tool Installation types, these types automatically appear in the dropdown list. Due to the specifics of the Tool Installation extension point in the Jenkins core, it’s not guaranteed that the configuration form displays properly. Missing or duplicated ToolInstallationProperty entries is one of known issues.

To make your Tool Installation compatible with the configuration snippet, follow examples in Jenkins JDK Tool. Tool Installation snippets for such implementations should work correctly out-of-the-box.

Opting a client controller out of shared configuration

In some cases, you may want a specific client controller to not receive any shared configuration. To do this, opt out of the client controller from shared configuration.

To do this, do the following:

Configure the client controller and choose Disable under the Shared Configuration section.

client master optout
If shared configuration is not disabled, then the same section provides information about the client controller’s ability to support this feature.
client master support

Opting operations center into shared configuration

It may be useful to opt operations center into the Shared Configuration. For example, where you are customizing tool installer locations on shared agents you will need those tool installers to be configured in operations center to be able to define the location overrides. Additional use cases include:

  • Configuring common alerts

  • Ensuring the email notification settings are consistently applied across the entire cluster

  • Applying a system message to the entire cluster

If you opt-in operations center it will pick up any Shared Configurations defined in the root of operations center.

To enable operations center to consume the shared configuration you must enable the Shared Configuration option from the operations center global configuration.

global config quick jump
Figure 4. Using the global configuration’s "Quick-Jump" navigation to find the Shared Configuration option
global config enabled
Figure 5. Enable consume shared configuration
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.