Introduction to Jenkins Configuration as Code (JCasC) with a Real Example

Jenkins Configuration as Code (JCasC), commonly referred to as JCasC, allows Jenkins administrators to manage the entire configuration of Jenkins, its plugins, jobs, and security settings in a declarative manner using YAML files. This approach is particularly useful for setting up Jenkins instances in a reproducible way and promoting Jenkins-as-a-Service in DevOps environments.

In this article, we’ll explore the basics of JCasC, explain its advantages, and walk through a real example of setting up Jenkins using JCasC.

What is Jenkins Configuration as Code (JCasC)?

Jenkins traditionally stores its configuration on disk as XML files. This configuration can include jobs, security settings, credentials, plugins, and other features. Managing large-scale Jenkins instances or replicating configurations between different instances (e.g., between environments) can become cumbersome when doing it manually.

JCasC solves this by allowing administrators to declare Jenkins configuration in a human-readable YAML format. With this approach, you can:

• Version-control the Jenkins configuration.
• Share the configuration between different environments (e.g., production, staging).
• Automate Jenkins instance setup.
• Easily replicate and manage configurations across different teams or projects.

Key Features of JCasC:

1. Declarative Configuration: All Jenkins settings are defined in a YAML file.
2. Version Control: JCasC configurations can be stored in Git repositories, enabling tracking and rollback.
3. Automated Setup: Once the YAML configuration is applied, the entire Jenkins instance is configured without manual intervention.
4. Compatibility with Plugins: Most Jenkins plugins are compatible with JCasC out of the box, allowing for complete configuration management.

How JCasC Works:

The core idea of JCasC is to define Jenkins configurations declaratively. Once the configuration-as-code plugin is installed, Jenkins can automatically read configurations from a YAML file upon startup, applying all the defined settings.

The main file used in JCasC is called jenkins.yaml or jcasc.yaml. You can specify everything from security realms to credentials and jobs in this file.

Real-world Example: Setting up Jenkins Using JCasC

Prerequisites:

• Jenkins installed (you can use a Dockerized Jenkins instance for simplicity).
• JCasC Plugin installed in Jenkins (configuration-as-code plugin).
• Basic knowledge of Jenkins settings.

Step 1: Install the JCasC Plugin

If you haven’t installed Jenkins with JCasC already, follow these steps:

1. Open your Jenkins dashboard.
2. Go to Manage Jenkins -> Manage Plugins.
3. In the “Available” tab, search for Configuration as Code Plugin and install it.
4. After installation, restart Jenkins.

Step 2: Create a JCasC YAML Configuration

Let’s create a jenkins.yaml file that sets up the following:

• Jenkins System Message (a message displayed on the Jenkins dashboard).
• Security Realm and Authorization (configuring Jenkins with admin user authentication).
• Installed Plugins (list of plugins to install).
• Jobs (example pipeline jobs).

Below is a basic YAML file for this configuration:

jenkins:
  systemMessage: "Welcome to Jenkins configured with JCasC!"
  
  # Security Settings
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "admin"
          password: "admin123"
          name: "Admin User"
          email: "admin@example.com"
  
  authorizationStrategy:
    loggedInUsersCanDoAnything:
      allowAnonymousRead: false

  # Tool Configuration (e.g., JDK)
  tools:
    jdk:
      installations:
        - name: "Java-11"
          home: "/usr/lib/jvm/java-11-openjdk"

  # Plugin Configuration
  plugins:
    required:
      - "git"
      - "workflow-aggregator"
      - "configuration-as-code"
  
  # Example Jobs
  jobs:
    - script: |
        pipelineJob('example-pipeline') {
          definition {
            cps {
              script("""
                pipeline {
                  agent any
                  stages {
                    stage('Build') {
                      steps {
                        echo 'Building...'
                      }
                    }
                    stage('Test') {
                      steps {
                        echo 'Testing...'
                      }
                    }
                    stage('Deploy') {
                      steps {
                        echo 'Deploying...'
                      }
                    }
                  }
                }
              """.stripIndent())
              sandbox(true)
            }
          }
        }

unclassified:
  location:
    adminAddress: "admin@example.com"

Explanation of the YAML File:

• System Message: This is the message displayed on the Jenkins dashboard, giving users basic information about the instance.
• Security Realm: Configures local user authentication with a pre-defined admin user. The user cannot sign up or change their password.
• Authorization Strategy: Only logged-in users can modify the Jenkins instance, with no anonymous read access allowed.
• Tools: Configures Java 11 as the default JDK for Jenkins jobs.
• Plugins: Lists the necessary plugins to install (git, workflow-aggregator, and configuration-as-code).
• Jobs: Defines a sample pipeline job with three stages (Build, Test, and Deploy). This job simply echoes messages at each stage.
• Unclassified Location Settings: Configures the Jenkins admin email address for notifications and alerts.

Step 3: Running Jenkins with JCasC

Using Docker

To demonstrate how JCasC works with Jenkins, we can run a Jenkins Docker container and mount the configuration YAML file.

Here’s how to do it:

1. Create a directory for Jenkins configurations (e.g., /jenkins_home/casc_configs).
2. Save your jenkins.yaml file into this directory.

Next, run the following Docker command:

docker run \
  -u root \
  -d \
  -p 8080:8080 \
  -p 50000:50000 \
  -v /jenkins_home:/var/jenkins_home \
  -v /jenkins_home/casc_configs:/var/jenkins_home/casc_configs \
  -e CASC_JENKINS_CONFIG=/var/jenkins_home/casc_configs/jenkins.yaml \
  jenkins/jenkins:lts

In this example:

• We are running Jenkins using Docker, exposing it on port 8080.
• We mount the directory with the JCasC YAML file to /var/jenkins_home/casc_configs inside the container.
• The CASC_JENKINS_CONFIG environment variable tells Jenkins where to find the configuration file.

Once the container is running, Jenkins will automatically load the jenkins.yaml configuration during startup.

Step 4: Verifying the Configuration

After Jenkins starts up, visit the Jenkins dashboard (typically accessible at http://localhost:8080):

1. Login using the credentials defined in the YAML (admin/admin123).
2. Check the System Message at the top of the dashboard. It should display: “Welcome to Jenkins configured with JCasC!”
3. Go to Manage Jenkins -> Manage Plugins. You should see that the git, workflow-aggregator, and configuration-as-code plugins are installed.
4. Jobs: Check the job list, and you should see the example-pipeline job created.

Advantages of Using JCasC

1. Consistency: With JCasC, the configuration is consistent across different Jenkins instances, making it easy to replicate environments.
2. Version Control: Store the YAML configuration in a Git repository, and you have an auditable history of changes.
3. Automation: Automating Jenkins setup with JCasC makes the entire CI/CD pipeline easier to manage.
4. Infrastructure-as-Code: JCasC fits seamlessly into the broader DevOps philosophy of treating infrastructure as code.

Conclusion

Jenkins Configuration as Code (JCasC) is a powerful tool that simplifies managing Jenkins at scale. By using YAML files to define everything from security settings to jobs, JCasC provides a declarative, version-controlled, and consistent way to manage Jenkins configurations. This makes it an excellent choice for organizations looking to adopt Infrastructure-as-Code (IaC) practices and automate their Jenkins instance setups.

With JCasC, you can easily replicate Jenkins instances, share configurations, and reduce human error by relying on code-based configuration. Whether you’re setting up Jenkins for the first time or managing multiple instances across different environments, JCasC can significantly improve your workflow.