Getting started with Jenkins Configuration as Code

I recently came across Jenkins Configuration as Code (JCasC), an interesting project that uses YAML formats for writing Jenkins configurations. YAML is been used in Kubernetes, Ansible, and many other technologies as a templating language. In this article, I will explain how to get started with JCasC in a container. Many people use Docker to run containers locally, but I'll be using Podman in my example. You can read more in Podman's Getting Started Guide guide if you need to set it up first.

Download a container image and start a Jenkins instance

To start a proof-of-concept JCasC on your local machine, run the following basic command (which I adapted from this repo):

kkulkarn@localhost  ~  podman run -p 8080:8080 -p 50000:50000 jenkins/jenkins:lts

Once the container is up, navigate to http://localhost:8080 to open the Jenkins user interface (UI) in your browser. It will ask you for a password—look at the logs from the podman run command, and you should see something like this in your terminal:

*************************************************************
*************************************************************
*************************************************************
 
Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:
 
63b9bde2015f4aedb75b93ec088e86ca
 
This may also be found at: /var/jenkins_home/secrets/initialAdminPassword
 
*************************************************************
*************************************************************
*************************************************************

This is the password that will unlock your Jenkins instance. You can follow the instructions to install recommended plugins and create a user (if you wish) or continue as an admin. This will open the familiar Jenkins UI.

Click Manage Jenkins -> Manage Plugins and install the following plugins:

• Configuration as Code AWS SSM secrets
• Configuration as Code Plugin - Groovy Scripting Extension
• Configuration as Code Support Plugin

Explore the JCasC plugin

Navigate back to Manage Jenkins and look for a new item near the bottom of the list—Configuration as Code:

Create a multibranch pipeline using JCasC and Script

Create a small config and update Jenkins:

jenkins:
  systemMessage: "Controlled by Configuration as Code"
jobs:
  - script: >
  	multibranchPipelineJob('configuration-as-code') {
      	branchSources {
          	git {
              	id = 'configuration-as-code'
              	remote('https://github.com/jenkinsci/configuration-as-code-plugin.git')
          	}
      }
}

You can save the file as casc.yml and push it to a URL where Jenkins can access it, like in this example:

Looking closely at this code, you can see there is a jenkins element that has a single item, systemMessage. This will put the specified message at the top of your Jenkins.

The jobs directive takes one script element that consists of a Groovy script that asks Jenkins to create a multibranch pipeline from a specified URL. This URL points to jenkinsci's configuration-as-code-plugin GitHub repo. This repo has a few branches, each with a Jenkinsfile. To upload this new config to Jenkins, navigate to Manage Jenkins->Configuration-as-Code and, under Replace configuration source with, paste the URL:

https://raw.githubusercontent.com/kedark3/jcasc-example/master/casc.yml

Click Apply new configuration. If it is successful, you should see Configuration loaded from: followed by the URL you entered.

Now look at your Jenkins dashboard:

A multibranch pipeline was loaded. You can also enter the URL of the seed job (the Groovy file) containing the code for it:

jenkins:
  systemMessage: "Controlled by Configuration as Code"
jobs:
  - script: >
      multibranchPipelineJob('configuration-as-code') {
          branchSources {
              git {
                  id = 'configuration-as-code'
                  remote('https://github.com/jenkinsci/configuration-as-code-plugin.git')
              }
          }
      }
  - url: https://raw.githubusercontent.com/kedark3/jcasc-example/master/seed.groovy

Click the Reload existing configuration button:

This will reload the configuration from the GitHub URL, and a new seed job will be created:

Add another config

Now add another config to your casc.yml file. For example, I wanted to add an Ansible Tower config. Before you do that, first install the Ansible Tower plugin from Manage Plugins. Then add the following to the end of your casc.yml file:

unclassified:
  ansibleTowerGlobalConfig:
	towerInstallation:
  	- enableDebugging: true
    	towerCredentialsId: ansible-tower-jenkins-user  # create these by hand in jenkins
    	towerDisplayName: Infra-Ansible-Tower-01
    	towerTrustCert: true
    	towerURL: https://infra-ansible-tower-01.example.com

This will be added under a new root element, unclassified, because it does not go under jenkins. Reload the config, and Ansible Tower will be added to your config. Navigate to Manage Jenkins -> Configure System:

Now you can manage Jenkins with Configuration as Code and host your code on a version-controlled site or repository.

Moving forward

JCasC is a way to take your Jenkins configuration a step closer to Infrastructure-as-Code (IaC), and it is still evolving.

There are many other demos available that you can use to update your casc.yml file. Also, all of this code is available on my GitHub repository. Please give JCasC a try, and share your thoughts in the comments!