Configuration as Code (CasC) for CloudBees Core simplifies the management of a CloudBees Core cluster by capturing the configuration of Core controllers in human-readable declarative configuration files which can then be applied to a controller 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 controllers while being centrally managed from CloudBees Core Operations Center.
The configuration bundle
The configuration of a controller 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 controllers, for example: controllers for building Maven projects, controllers for building Golang docker images, etc.
A configuration bundle contains:
The list of plugins to install (
plugins.yaml
)
A Plugin Catalog (
plugin-catalog.yaml
)
The Jenkins configuration (
jenkins.yaml
)
The bundle descriptor (
bundle.yaml
)
When a controller 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
plugins.yaml
Apply/Update the Jenkins configuration from
jenkins.yaml
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 controller in your cluster.
Configure it as you like (plugins and global configuration).
Optionally configure a Plugin Catalog.
Finally, visit
/core-casc-export
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 controllers. 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-controller
(The bundle in this SCM is for a controller named “my-java-controller”. For more information, see the official documentation)
Creating a controller
To apply a CloudBees Core CasC bundle to a controller on CloudBees Core for modern platforms, all you need to do is name the controller 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 controller 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.
Architecture
As noted before, Operations Center is the distributor of bundles inside the CloudBees Core cluster. It stores and serves bundles to controllers, but can also pull them from an external SCM.
controllers send requests for their bundles through a secure HTTP(S) endpoint in Operations Center. Each controller 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.
Traditional platforms
When using CloudBees Core on traditional platforms the bundle-link.yaml file needs to be created manually and connected to the controller 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 controller (or Team controller), if the bundles’ storage does not contain a bundle with a name that matches the controller name, a link file is automatically created and connected to the controller.
Note: This linking by naming convention mechanism might change in the future, so that the user creating the controller can select which bundle is applied.
Handling configuration updates
After the initial configuration on startup, there is a background process in the controller 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 controller 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.