Configuration as Code

8 minute read

CloudBees no longer supports CloudBees Jenkins Distribution as of February 24, 2021. Please refer to the following step-by-step documentation for Migrating from CloudBees Jenkins Distribution to Jenkins LTS. The increased alignment between CloudBees Jenkins Distribution and Jenkins means users will experience zero impact to Pipeline execution. Existing customers can also contact CloudBees Support to help ensure a smooth transition.

Please see About the CloudBees Jenkins Distribution retirement for more information.

Configuration as Code for CloudBees Jenkins Distribution and CloudBees Jenkins Support are Preview features.


A Preview feature:

  • Has not undergone end-to-end testing with CloudBees products

  • Is provided without service-level agreements (SLA) and therefore does not include CloudBees' commitment on functionality or performance

  • May impact other stable areas of the product when used

  • May have limited documentation

  • May not be feature complete during the Preview period

  • May graduate from preview state to fully supported or be removed from the product

  • May introduce incompatible, backward-breaking changes that could revoke the ability to upgrade

Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

One of the key concepts in cloud native DevOps is "everything as code".

In the "everything as code" world, you can use code-management tools to deal with complex things like configurations and customizations. For example, managing configuration as code permits you to make use of tools like versioning, code comparison and replication for things that you’d traditionally configure using a point-and-click user interfaces.

CloudBees Jenkins Distribution and Jenkins are no exception to the "everything as code" model. As anyone who has set up a new Jenkins instance knows, setting up the instance and configuring all of its plugins properly can be a detailed, time-consuming process, especially when you’re using the Manage Jenkins user interface to do everything.

The release of CloudBees Jenkins Distribution considerably simplified the installation and configuration process, and Configuration as Code makes the configuration of CloudBees Jenkins Distribution even easier. With Configuration as Code, you can turn complex configurations into easily-replicated, human-readable code files, and you can manage those configuration files with source control tools like GitHub.

Key features

The Configuration as Code plugin provides a wide range of "configuration as code" features:

  • You can configure a full environment using a simple human-readable YAML configuration file to:

    • Configure new instances

    • Restore existing instances

    • Spin up duplicate instances quickly and safely

  • Configuration as Code automatically validates and applies configuration files.

  • Configuration as Code provides a REST API for programmatic access.

  • For advanced users, Configuration as Code features a command-line interface (CLI) for management.

  • You can export a running instance’s current configuration of a running instance into a YAML file. This YAML file can be modified and used to configure new instances. the Exporting configurations page within the repository

Quick start for Configuration as Code

This section of the topic provides a Quick Start for Configuration as Code in CloudBees Jenkins Distribution. These guidelines may be useful if you are evaluating the Configuration as Code plugin or if you are an early adopter of the plugin while it’s in the Technical Preview phase.

Before you get started

This guide makes two assumptions:

  • That you have a running CloudBees Jenkins Distribution or Jenkins instance to use as a configuration source.

  • That the running instance is CloudBees Jenkins Distribution version or higher.

Installing the Configuration as Code plugin

First, install the plugin:

  1. Open the CloudBees Jenkins Distribution user interface.

  2. Click on Manage Jenkins Manage Plugins.

  3. Click on the Available tab.

  4. Use the Filter field to search for Configuration as code.

  5. Click the checkbox to select the Configuration as Code Plugin.

  6. Click Install without restart to install the plugin.

Preparing an initial YAML configuration file

Next, prepare an initial YAML configuration file to use as the configuration source:

  1. Export a copy of the instance’s running configuration as a YAML file by clicking Manage Jenkins Configuration as CodeDownload Configuration.

  2. The instance saves a file called jenkins.yaml to your local workstation.

  3. The exported YAML file contains almost all of the system’s configuration, including views, agents and credentials: for the full details of the configuration format, see Exporting Configurations in the plugin’s repository.

Modifying the YAML configuration for reuse

If you want to use the exported YAML file to configure other instances, you’ll need to review and most likely update the exported file. You can modify YAML files with any text editor, although you may want to use a text editor that supports YAML syntax highlighting to make things easier to read.

Secrets in the exported file

Because secrets are exported as encrypted strings, and those strings may only be decrypted by the same CloudBees Jenkins Distribution instance. This isn’t a problem if you’re using the exported configuration to restore an instance, but if you want to use this configuration file on a new instance, you’ll have to replace those credentials.

CloudBees strongly discourages the use of plaintext values for configuration file secrets: instead, you should use Secret Resolvers or externalize your credentials with tools like the Kubernetes Credentials plugin.

Stack trace errors

If you see stack trace errors in the exported configuration file, it indicates that a given plugin in your instance either lacks Configuration as Code support entirely or has poorly implemented Configuration as Code support. If you encounter these types of errors, please contact CloudBees Support and let us know, as we maintain lists of known incompatibilities: see Known Limitations.

Limitations of exported data

Not all of the instance’s information is exported into the YAML configuration file.

The YAML files exported by the Configuration as Code plugin contain only the data used to configure the instance: they are not full backups of your instance, and must not be used for this purpose!

Applying the modified YAML configuration file to a new instance

Once you’ve created and adapted a YAML configuration file for your needs, you can apply it to a new instance. The following guidelines are for two different use cases:

Applying configuration files to non-Docker instances

To apply an exported and modified YAML configuration file to an instance installed using a method other than Docker or Helm charts:

  1. Back up the target instance in case something goes wrong during the configuration process. This is a strongly recommended step because the Configuration as Code plugin only appends or replaces the target instance’s configuration values, and does not invalidate or remove existing configuration information. Therefore, it’s possible for configurations specified with a YAML file to conflict with existing configuration values.

  2. If you intend to use Configuration as Code to further configure the instance after importing the YAML configuration file, install the plugin as detailed in Installing the Configuration as Code plugin. If the Configuration as Code plugin is already installed on the instance, you can skip this step.

  3. Copy the exported and modified jenkins.yaml file into your JENKINS_HOME directory. To use a different directory for your jenkins.yaml file, create a CASC_JENKINS_CONFIG environment variable that specifies the alternate location. For example, you could specify a configuration file location using the syntax ENV CASC_JENKINS_CONFIG /var/my-configurations/source-file-for-all-instances.yaml.

  4. Restart the instance

  5. The startup log indicates the Configuration as Code initialization process:

    1. If something is wrong with the configuration information, CloudBees Jenkins Distribution will interrupt initialization, and you’ll need to further modify jenkins.yaml to address the issue before restarting the instance again.

    2. If something is wrong with one of the plugins (for example, a previously unknown compatibility issue), the instance prints errors to the startup log but will continue to initialize. After the instance is running, you’ll need to stop the instance, fix the plugin configuration, and restart the instance.

  6. Once the instance has started, verify that the configuration has been properly applied to the instance by comparing the target instance to the source instance.

Applying configuration files to Docker instances

As of August 2019, CloudBees Jenkins Distribution Docker images do not have built-in plugin management capabilities like the script for official Jenkins Docker images or CloudBees CI Plugin Catalogs. For the Preview phase of Configuration as Code, we have extended an official Jenkins Image, and this can be used for both CloudBees Jenkins Distribution and Jenkins LTS users.

There is a demonstration repository for the use of Configuration as Code with CloudBees Jenkins Distribution in Docker, and you can use that demonstration repository as a reference for the following set of instructions.

Preparing the Docker image

To prepare a Docker image for Configuration as Code in CloudBees Jenkins Distribution:

  1. Create a new repository.

  2. Create a Dockerfile in the repository which resembles the example Dockerfile. The example Dockerfile has the following characteristics:

    • It specifies a multi-stage Docker build where the first stage retrieves the CloudBees Jenkins Distribution WAR file and replaces the jenkins.war file from the community image.

    • It uses jenkins.yaml as its configuration source file.

    • It installs all CloudBees Jenkins Distribution plugins by default using a system property: this behavior can be disabled in your own instance.

    • It runs the community build-time plugin-management scripts, which process the contents of the plugins.txt file.

    • It uses the CloudBees Update Center as the source of truth for its plugins, aligning plugin versions with the versions listed in the Web UI Update Center.

  3. Add your local exported and modified jenkins.yaml file to the repository.

  4. Add the plugins.txt file to your repository, using the example plugins.txt file as a reference.

  5. Edit the plugins.txt file:

    • Add the most recent version of the configuration-as-code plugin: otherwise, the Configuration as Code plugin will not be installed.

    • Add any plugins you’re using which are not included in the default CloudBees Jenkins Distribution installation. Note that some plugin compatibility fixes may not yet be included in CloudBees Jenkins Distribution due to integration testing and release cycles.

    • If necessary, you can override plugin versions as demonstrated in the example plugins.txt file.

Building the Docker image

After you’ve prepared your configuration files, you can build the Docker image using standard Docker commands:

docker build -t ${mycompany}:cjd-jcasc-test .

This command causes Docker to execute the specified Dockerfile (cjd-jcasc-test). This Dockerfile includes the plugin management section, and adds CloudBees Jenkins Distribution, any additional plugins specified in plugins.txt, and the jenkins.yaml file to the image, producing a ready-to-use, fully-preconfigured Docker image.

Running and testing the Docker image

The Docker image for the Technical Preview is based on the community image, and includes all of the features listed in the official community Jenkins image documentation.

To run the Docker image:

  1. Use the docker run command to start the image:

    shell% docker run --rm -p 8080:8080 ${mycompany}:cjd-jcasc-test
  2. The startup log includes the Configuration as Code initialization process:

    1. If something is wrong with the configuration information, CloudBees Jenkins Distribution will interrupt initialization, and you’ll need to further modify jenkins.yaml to address the issue before restarting the instance again.

    2. If something is wrong with one of the plugins (for example, a previously unknown compatibility issue), the instance prints errors to the startup log but will continue to initialize. After the instance is running, you’ll need to stop the instance, fix the plugin configuration, and restart the instance.

  3. Using a browser client, navigate to http://localhost:8080.

  4. If you have configured an administrative user in jenkins.yaml, log in using the specified credentials.

  5. If you have not configured an administrative user, go through the initial administrative user setup process using the instance’s secret key (provided in the startup logs during the initialization process).

  6. On the Register CloudBees Jenkins Distribution screen, click Activate Online and register the CloudBees Jenkins Distribution instance. Although CloudBees Jenkins Distribution is free forever, you will need to accept the license agreement.

  7. On the Customize CloudBees Jenkins Distribution screen:

    1. Click on Select plugins to install None to deselect all plugins.

    2. Click Install.

  8. The CloudBees Jenkins Distribution instance has been configured using Configuration as Code and is ready to run!

  9. Review the updated target instance against the source instance to confirm that the configuration has been properly applied.

Extending an instance’s configuration

You may want to extend or otherwise alter a configuration that you’ve updated using Configuration as Code. For instructions on how to do so, see the Configuration as Code documentation in the Configuration as Code repository.

Known limitations

Known issues with the Configuration as Code plugin are tracked in the community Jenkins issue tracker.

Plugins with known compatibility issues are tracked in the following CloudBees-maintained locations (although most plugins are compatible with Configuration as Code):

Some community plugins may have known issues that can prevent CloudBees Jenkins Distribution from starting or being properly configured: these plugins should be used with caution, and we strongly recommend backing up your instance before using these plugins with Configuration as Code.