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 email 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.
Create 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 want five (A, B, C, D, and E) of them to have the same email configuration (for example, an SMTP server or Jenkins instance email) yet only three of the client controllers (C, D, and E) to have the alerting information you need to create one item to contain the email 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 email configuration is created in Folder One.
| To obtain the correct hierarchy, you may have to move the client controllers to different folders. |
-
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.
-
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.
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 titleSnippets with different keys are combined into the configuration.
Email 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 NameSnippets with different keys are combined into the configuration.
If multiple snippets 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.
Understand snippet types
Use the 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.
Configure the tool installation
Each Tool Installation snippet defines one installation of a tool. It is possible to set up multiple Tool Installations. To do this, do the following:
-
Create a new Tool Installation snippet.
-
Select a tool type to snippet.
-
Configure the tool according to the guidelines available in the built-in help 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
Figure 1. Select the snippet
Figure 2. Select tool to be installed
Figure 3. Set up a tool (JDK from Jenkins Core)
-
Understand 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 ware 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. |
Review tested tools
The Tool Installation Snippet has been tested with the following tools:
-
JDK from the Jenkins core
-
Maven from the Jenkins core
-
Git CLI client from Git Client Plugin
-
Docker CLI client from Docker Commons Plugin
A correct behavior for other Tool Installation types is not guaranteed.
If you determine there are any issues with the configuration propagation, please contact the CloudBees Support team.
Configure the 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.
Opt a client controller out of a 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.
| If shared configuration is not disabled, then the same section provides information about the client controller’s ability to support this feature. |
Opt the operations center into a 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 to the operations center, it picks up any Shared Configurations defined in the root of the operations center.
To enable the operations center to consume the shared configuration you must enable the Shared Configuration option from the operations center global configuration.
