A dive into Jenkins Configuration as Code (JCasC)

In today's fast-paced DevOps world, automation is key to maintaining efficiency and consistency across development, testing, and deployment processes. Jenkins, a popular open-source automation server, offers a powerful feature called Jenkins Configuration as Code (JCasC). This allows you to manage your Jenkins configurations in a human-readable and declarative manner using YAML files, ensuring your setup is consistent, reproducible, and version-controlled.

In this blog post, we'll explore the benefits of JCasC and walk through a sample use case to get you started.

What is Jenkins Configuration as Code (JCasC)?

Jenkins Configuration as Code (JCasC) allows you to define and configure Jenkins instances using YAML files. This means you can describe all aspects of your Jenkins setup —from global configurations to job definitions— in a version-controlled repository.

Creating the Dockerfile

The Dockerfile provided below sets up Jenkins with the necessary plugins and configurations using JCasC:

FROM jenkins/jenkins:lts-jdk17

# Install Jenkins plugins
COPY plugins.txt /usr/share/jenkins/ref/plugins.txt
RUN jenkins-plugin-cli --plugin-file /usr/share/jenkins/ref/plugins.txt

# Disable the setup wizard as we will set up Jenkins as code
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"

# Copy the Configuration as Code (CasC) YAML file into the image
COPY jenkins-casc.yaml /var/jenkins_home/casc_configs/jenkins.yaml

# Tell the Jenkins Configuration as Code plugin where to find the YAML file
ENV CASC_JENKINS_CONFIG="/var/jenkins_home/casc_configs/jenkins.yaml"

In this Dockerfile, we start with the jenkins/jenkins:lts-jdk17 image, ensuring we have a stable Jenkins version with JDK 17.

The jenkins-plugin-cli is a command-line tool that installs Jenkins plugins specified in plugins.txt, streamlining the setup of necessary plugins.

The JAVA_OPTS environment variable disables the Jenkins setup wizard since we are configuring Jenkins using JCasC.

The COPY commands include the required plugins.txt and jenkins-casc.yaml files into the Docker image.

Finally, the CASC_JENKINS_CONFIG environment variable points Jenkins to the location of the JCasC YAML file, allowing it to automatically apply the specified configurations at startup.

Specifying Plugins

To ensure Jenkins has the necessary plugins for its operations, create a plugins.txt file. This file lists the required plugins and their versions:

git:5.0.0
workflow-aggregator:600.vb_57cdd26fdd7
configuration-as-code:1810.v9b_c30a_249a_4c
matrix-auth:3.2.2
job-dsl:1.87

Each line in plugins.txt specifies a plugin. You can include the version after a colon (e.g., git:5.0.0) to ensure a specific version is installed. If you omit the version (e.g., git), the latest version of the plugin will be installed when the image is built. Specifying versions can help maintain consistency across different environments by ensuring the same plugin versions are used.

The matrix-auth plugin is useful for managing access control in Jenkins environments where multiple users or teams interact with Jenkins. We'll need it later when we set up users and assign them different roles based on their responsibilities.

On the other hand, job-dsl Plugin adds support for defining Jenkins jobs using Groovy DSL scripts.

Note: The configuration-as-code plugin is essential for JCasC to function. It enables Jenkins to read the YAML configuration file and apply the specified settings automatically.

Configuring Jenkins with JCasC

Create a jenkins-casc.yaml file to configure Jenkins. In this blog, we will define user authentication, tool installations, and a sample job. Here’s a comprehensive example:

jenkins:
  systemMessage: "Jenkins configured automatically by Jenkins Configuration as Code plugin"

  # Security Realm for user authentication
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "admin"
          password: "admin"

        - id: "developer"
          password: "developer"

        - id: "viewer"
          password: "viewer"


  # Authorization Strategy
  authorizationStrategy:
    projectMatrix:
      entries:
        - user:
            name: admin
            permissions:
              - Overall/Administer
        - user:
            name: developer
            permissions:
              - Overall/Read
              - Job/Build
        - user:
            name: viewer
            permissions:
              - Overall/Read



# Tool Configuration
tool:
  git:
    installations:
      - name: "Default"
        home: "/usr/bin/git"
  maven:
    installations:
      - name: maven3
        properties:
          - installSource:
              installers:
                - maven:
                    id: "3.8.4"

# Sample Job Configuration
jobs:
  - script: >
      pipelineJob('example-pipeline-job') {
      definition {
        cps {
            script('''
                pipeline {
                    agent any
                    stages {
                        stage('Build') {
                            steps {
                                echo 'Building...'
                            }
                        }
                        stage('Test') {
                            steps {
                                echo 'Testing...'
                            }
                        }
                        stage('Deploy') {
                            steps {
                                echo 'Deploying...'
                            }
                        }
                    }
                }
            ''')
            }
          }
        } 

User authentication is defined in the securityRealm section, where local user authentication is configured, and self-signup is disabled for security. Three users are predefined: admin, with full administrative access; developer, with read and build permissions; and viewer, with read-only access. This setup ensures appropriate access levels based on user roles.

Authorization is handled by the Project-based Matrix Authorization Strategy in the authorizationStrategy section. This strategy provides granular control over user permissions, giving the admin full control with (Overall/Administer), while both the developer and viewer have read access to the overall Jenkins instance (Overall/Read), with the developer also having the ability to build jobs (Job/Build).

The tool section Specifies the configuration for tools that Jenkins will use, in our case: git and Maven. The git tool is set up with a default installation path, and Maven is installed ensuring that these tools are readily available for use in jobs.

The jobs section defines a sample pipeline job using a script block.

Build and Run the Docker Container

Now, we'll build and run our Docker container.

# Build the Docker image
docker build -t jenkins-jcasc .

# Run the Docker container
docker run --name jenkins -p 8080:8080  jenkins-jcasc

Once the container is running, you can access Jenkins at http://localhost:8080 and log in using one of the user credentials created earlier.

We can notice the system message we defined earlier and the sample pipeline.

You can find the code used for this blog in the following repository: https://github.com/SelmaGuedidi/JCasC

Reference

For further information on Jenkins Configuration as Code (JCasC), you can consult these sources:

Configuration-as-code plugin documentation: https://plugins.jenkins.io/configuration-as-code/

demos: https://github.com/jenkinsci/configuration-as-code-plugin/tree/master/demos

Conclusion

Jenkins Configuration as Code simplifies the management of Jenkins configurations, making your CI/CD pipeline more robust and easier to maintain. By leveraging Docker and JCasC, you can quickly set up consistent Jenkins environments that are easy to reproduce and update.

Try out JCasC in your projects and experience the benefits of a streamlined, automated Jenkins setup. Happy automating!