Configuration as Code (CasC) for Masters

The bundle.yaml file is an index file that describes the bundle and references the other files in the bundle. The file must contain all of the properties listed below:

This file is the main Configuration as Code (CasC) for Masters configuration file that describes the master. For more information on how to format this file, see the documentation of the Jenkins Configuration-as-Code plugin.

This file lists all of the plugins that should be installed on the master. All plugins listed must be in the CloudBees Assurance Program (CAP). Plugins outside of CAP (for example, Open Source or your own plugins) should be added via a Plugin Catalog (see the next section).

The contents of this file should be a list of plugin IDs. Find many popular plugins and their IDs at the following sites:

This file defines the catalog of plugins that are available for installation on the master. The plugin catalog contains a list of plugins along with the version that should be installed. An optional location can also be specified for plugins that are not available in the standard update centers. For more information on Plugin Catalogs, see Configuring plugin catalogs.

Install the Configuration as Code plugin

After creating a configuration bundle based on the export files, add the bundle as a new master and connect it to Operations Center using a casc-bundle-link.yaml file. See Setting up a Client Master for more information.

The original test master created in the UI can be deleted as it is no longer needed.

To deploy a Configuration as Code (CasC) for Masters bundle to the Operations Center, copy the directory containing the bundle files to your $JENKINS_HOME/jcasc-bundles-store directory. Ensure the owner and group of the bundle directory and files match those of other files under $JENKINS_HOME and are sufficient to allow the Jenkins user to read the files.

Configuration as Code (CasC) for Masters bundles can be in one or more SCM repositories; however, this guide assumes all bundles are in the same Git repository, with the following layout:

Operations Center distributes bundles from local storage, so to use files from an external SCM system you must create a Freestyle job to pull those bundles from the SCM to local storage.

To create a job to pull Configuration as Code (CasC) for Masters bundles from an SCM to local storage:

Afterwards, Configuration as Code (CasC) for Masters bundles should be available in local storage and ready to be used by masters following the normal procedure.

One way to trigger a Freestyle job to pull Configuration as Code (CasC) for Masters bundles from an SCM is through the use of webhooks. If your SCM supports Webhooks, configure a webhook in the SCM to trigger builds on the importing job on push events.

Setting up a webhook through your SCM will ensure a change made in the repository will be automatically available to masters using the Configuration as Code (CasC) for Masters bundle.

The version attribute of this file needs to be updated (incremented) when something changes in the bundle (in any other file). Other attributes rarely change (they are just pointing to the other files in the bundle).

If the version attribute is not incremented then connected masters will not get the changes in the bundle.

CloudBees Assurance Program (CAP) Tier 1 plugins can be added to your master by adding the plugins to this file. Deleting plugins from the file will not remove them from the master. To remove plugins from the master, delete them in the UI, and before restarting the master, delete them from the plugins.yaml file or they will be reinstalled.

For more information on the CloudBees Assurance Program and how CloudBees classifies plugins see CloudBees plugin support policies.

When adding a plugin to the plugin-catalog.yaml file which is not a CloudBees Assurance Program (CAP) Tier 1 plugin, all of its dependencies also need to be included either in the plugin-catalog.yaml file or this file if they are Tier 1 in CAP. If the dependencies are not in either file, then the plugin will not be installed and their absence could potentially cause other issues (ie. configuration from jenkins.yaml not applicable thus a start up error).

If you want to add a plugin to your master that is not in CloudBees Assurance Program (CAP) as Tier 1, add the plugin to the this file. You will also need to add the plugin’s dependencies either to this file or the plugins.yaml file if they are in CAP as Tier 1.

The plugins in the this file need to be compatible with the set of CAP Tier 1 plugins in the plugins.yaml file. A validation of the plugin-catalog.yaml file is run at startup time. If this validation fails, the plugins in the`plugin-catalog.yaml` file are not installed and your master will continue with its normal startup. This scenario means plugins are not installed, which might lead to other issues (ie. specific configurations in jenkins.yaml can not be applied).

This file is edited to change or add Jenkins configurations. There is a wide variety of possible combinations (depending on the plugins being configured as code). This file is entirely managed by the OSS Jenkins Configuration as Code (JCasC) plugin. In other words, all OSS documentation, reported bugs, community blogs, Gitter chats, etc. apply to this file.

The bulk of the content in this file is defined by the various plugins you have installed with only a small portion of it defined by the Jenkins core itself. However, there are a few general items to consider when editing the file:

The connection details needed in the casc-bundle-link.yaml file, the location of the bundle and the access token required to grant access, are available in Operations Center. To create the casc-bundle-link.yaml file, download the casc-bundle-link.yaml file from Operations Center and save it anywhere in the master’s filesystem.

The casc-bundle-link.yaml file contains the following properties:

The Client Master is directed to use the casc-bundle-link.yaml file by setting a Java system property. On startup, the Client Master will read the casc-bundle-link.yaml file, fetch its Configuration as Code (CasC) for Masters bundle from the Operations Center using the details specified in the casc-bundle-link.yaml file, then initialize itself with the provided configuration.

To point the Client Master at the casc-bundle-link.yaml file, set the Java system property core.casc.config.bundle to the location of the link file. For example, to start a Client Master using the casc-bundle-link.yaml file at $JENKINS_HOME/casc-bundle-link.yaml use the following command: java -Dcore.casc.config.bundle=$JENKINS_HOME/casc-bundle-link.yaml -jar jenkins.war

After you start the Client Master with the correct java system property, open Operations Center and connect the Client Master in the UI.

The Master Path attribute of a bundle indicates to what master the bundle will be applied. This value must be the full path of the master item in Operations Center and it needs to be set before the master is provisioned. If it’s set after the master is provisioned then a re-provisioning is needed for the configuration to take effect.

This action re-generates the access token for a bundle. Regenerating the access token is not usually required and should only be done in certain situations. If there is a master using the regenerated bundle, it will lose access to it.

If the token needs to be re-generated (for example, for security reasons) then the master using the token needs to be properly reconfigured (if it is a Client Master). The casc-bundle-link.yaml file needs to be updated with the new token.

As described in other sections, the casc-bundle-link.yaml file is a YAML formatted file containing the URL and the token to access the bundle in Operations Center. This action copies the content of that file to the clipboard.

This action downloads the casc-bundle-link.yaml file.

The security token and Configuration as Code (CasC) for Masters bundle both contain sensitive information, so it is recommended that they are protected by using HTTPS when sent between the Operations Center and master. HTTPS must be enabled on the Operations Center side. Typically enabling HTTPS is done by terminating the secure connection externally in a reverse proxy, but it can also be terminated in the Jenkins server. To enable HTTPS, add startup parameters to specify the HTTPS port, server certificate, and key.

If you are using this method in a limited scope for test deployments, see “Set-up SSL on a CJP environment with a self-sign SSL certificate on each Jenkins box”, a CloudBees Knowledge Base article, for guidance on setting up CloudBees CI with self-signed certificates.

The Plugin Installation Manager Tool can be used to assist with determining the full list of a plugin’s transitive dependencies. The tool takes as input a plugins.yaml that lists plugins you would like to install and outputs a list of all the plugins to be installed, along with all their transitive dependencies. This list can then be used to populate the plugin catalog so the plugins specified in plugins.yaml can be successfully installed.

Jenkins 2.199 introduced a check to prevent saving global configurations before they are loaded. Configuration as Code (CasC) for Masters needs to apply global configurations before Jenkins loads jobs to correctly reference any global state. Therefore, until JENKINS-51856 is implemented, there is a race condition where Jenkins may fail to start when used with the Configuration as Code plugin.

If you encounter the race condition, Jenkins will fail to start with an exception message similar to the following:

The workaround for this race condition is to delay Configuration as Code (CasC) for Masters configuration to give Jenkins time to load the global configuration.

To enable this delay, set the io.jenkins.plugins.casc.ConfigurationAsCode.initialDelay system property to the amount of delay time in milliseconds. This delay time value will be dependent on aspects of your system (cpu/disk) and configuration.

To find a value that will work with your system, start with 5000 (5 seconds) and increment by 2000 (2 seconds) until the issue is corrected, then add 1000 (1 second) to the final value for extra safety.