Configuration as Code (CasC) for CloudBees Core simplifies the management of a CloudBees Core cluster by capturing the configuration of Core masters in human-readable declarative configuration files which can then be applied to a master in a reproducible way. By capturing the configuration in files, it can be treated as a first class revision-controlled artifact - versioned, tested, validated, and then applied to masters while being centrally managed from CloudBees Core Operations Center.
The configuration bundle
The configuration of a master is described in a collection of YAML files referred to as a Core CasC bundle (the “configuration bundle” in the rest of the blog, for simplicity). The Operations Center can store many different configuration bundles representing a selection of predefined masters, for example: masters for building Maven projects, masters for building Golang docker images, etc.
A configuration bundle contains:
The list of plugins to install (
A Plugin Catalog (
The Jenkins configuration (
The bundle descriptor (
When a master is configured to use a configuration bundle, the following actions occur during start up if the bundle.yaml version has changed:
Install/Update the Plugin Catalog
Install/Update the list of plugins from
Apply/Update the Jenkins configuration from
See more details about Configuration Bundles in the documentation.
How to use it
Creating a starting configuration bundle
A blank slate is not ideal when there is a lot to define. It’s easier to configure Jenkins using the UI and then export that configuration as a Configuration Bundle.
Create a Test Master in your cluster.
Configure it as you like (plugins and global configuration).
Optionally configure a Plugin Catalog.
The response will be a composed YAML file containing all the components of the configuration bundle. Split them into separate YAML files and put them into a folder; that’s your configuration bundle!
NOTE: The exported jenkins.yaml may contain default values that can be removed and it might have some incorrect sections (coming from plugins that are not fully compatible with OSS JCasC). So use this export as a starting point to be adapted, as it might not be usable as is.
Setting up Operations Center
Operations Center distributes configuration bundles to masters. Because Operations Center has the ability to run administration jobs, it can be configured to retrieve the bundles from an SCM. To retrieve CasC bundles from an SCM, create a simple Freestyle job that checks out the SCM with the bundles and add the following shell step:
cp * /var/jenkins_home/jcasc-bundles-store/my-java-master
(The bundle in this SCM is for a master named “my-java-master”. For more information, see the official documentation)
Creating a master
To apply a CloudBees Core CasC bundle to a master on CloudBees Core for modern platforms, all you need to do is name the master the same name as the bundle. There are additional manual steps when using CloudBees Core on traditional platforms. Read more about this in the documentation and next sections here.
NOTE: Each configuration bundle is protected by an access token. Before connecting a master to a bundle, a token needs to be created. This process is manual (at least during the Preview Release). See how to create a security token in the documentation.
As noted before, Operations Center is the distributor of bundles inside the CloudBees Core cluster. It stores and serves bundles to masters, but can also pull them from an external SCM.
Masters send requests for their bundles through a secure HTTP(S) endpoint in Operations Center. Each master is aware of which bundle it is connected to through the bundle-link.yaml file that contains the URL of the bundle to use and the access token.
When using CloudBees Core on traditional platforms the bundle-link.yaml file needs to be created manually and connected to the master to use it (by using a JVM property).
Modern platforms (Kubernetes)
Users do not need to manually create the link file when using CasC for CloudBees Core on modern platforms. When using Operations Center to provision a new Managed Master (or Team Master), if the bundles’ storage does not contain a bundle with a name that matches the master name, a link file is automatically created and connected to the master.
Note: This linking by naming convention mechanism might change in the future, so that the user creating the master can select which bundle is applied.
Handling configuration updates
After the initial configuration on startup, there is a background process in the master which is checking for updates of the configuration bundle on Operations Center. If there is an update, then the update process shows an Administrative Monitor in the master to inform the user about the new available configuration.
Depending on the configuration change, the new configuration may be able to be applied without a restart (for example when the update contains no changes to plugin versions or there are no new plugins to be installed).
In this Preview Release, there is no built-in support to retrieve the configuration from an SCM, so a specific job can be created in Operations Center to retrieve bundles from an SCM (including the use of webhooks if desired). There is more information about how to configure this in the documentation.
Stay up to date
We'll never share your email address and you can opt out at any time, we promise.