Jenkins configuration as code (JCasC) - Commands & Configuration

Introduction

Jenkins configuration as code lets you set up Jenkins automatically using a file. This solves the problem of manually clicking through settings every time you install Jenkins or want to share your setup.

When you want to quickly recreate the same Jenkins setup on a new server without manual steps

When you want to keep your Jenkins settings in version control to track changes

When you want to automate Jenkins setup as part of your infrastructure deployment

When you want to share your Jenkins configuration with your team easily

When you want to avoid mistakes from manual configuration by using a single source of truth

Config File - jenkins.yaml

jenkins.yaml

jenkins:
  systemMessage: "Welcome to Jenkins configured as code!"
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "admin"
          password: "admin123"
  authorizationStrategy:
    loggedInUsersCanDoAnything:
      allowAnonymousRead: false
  tools:
    git:
      installations:
        - name: "Default"
          home: "/usr/bin/git"
  nodes:
    - permanent:
        name: "built-in"
        remoteFS: "/var/jenkins_home"
        labelString: "master"
        launcher:
          jnlp:
            workDirSettings:
              disabled: false
              internalDir: "remoting"
              failIfWorkDirIsMissing: false

This YAML file sets Jenkins configuration as code.

• systemMessage: Shows a welcome message on Jenkins dashboard.
• securityRealm: Defines user login settings with one admin user.
• authorizationStrategy: Allows logged-in users full access, no anonymous read.
• tools: Configures Git tool location.
• nodes: Defines the built-in Jenkins node with JNLP launcher.

Commands

Starts Jenkins server on port 8080 with admin user and disables setup wizard for automation.

Terminal

java -jar jenkins.war --httpPort=8080 --argumentsRealm.passwd.admin=admin123 --argumentsRealm.roles.admin=admin -Djenkins.install.runSetupWizard=false

Expected Output

Running from: /home/user/jenkins.war

2024-06-01 12:00:00.000+0000 [id=1]    INFO    org.eclipse.jetty.server.Server#main: Started @12345ms

2024-06-01 12:00:01.000+0000 [id=1]    INFO    hudson.WebAppMain#contextInitialized: Jenkins is fully up and running

→

--httpPort=8080 - Sets Jenkins to listen on port 8080

→

--argumentsRealm.passwd.admin=admin123 - Creates admin user with password

→

-Djenkins.install.runSetupWizard=false - Skips initial setup wizard

Applies the Jenkins configuration as code from the jenkins.yaml file to set up Jenkins automatically.

Terminal

curl -X POST -H "Content-Type: application/yaml" --data-binary @jenkins.yaml http://localhost:8080/configuration-as-code/apply

Expected Output

{"status":"success","message":"Configuration applied successfully"}

→

-X POST - Sends data to Jenkins to apply configuration

→

-H "Content-Type: application/yaml" - Specifies the data format as YAML

→

--data-binary @jenkins.yaml - Uploads the YAML configuration file

Exports the current Jenkins configuration as YAML to verify what is set.

Terminal

curl http://localhost:8080/configuration-as-code/export

Expected Output

jenkins:

  systemMessage: "Welcome to Jenkins configured as code!"

  securityRealm:

    local:

      allowsSignup: false

      users:

        - id: "admin"

          password: "admin123"

  authorizationStrategy:

    loggedInUsersCanDoAnything:

      allowAnonymousRead: false

  tools:

    git:

      installations:

        - name: "Default"

          home: "/usr/bin/git"

  nodes:

    - permanent:

        name: "built-in"

        remoteFS: "/var/jenkins_home"

        labelString: "master"

        launcher:

          jnlp:

            workDirSettings:

              disabled: false

              internalDir: "remoting"

              failIfWorkDirIsMissing: false

Key Concept

If you remember nothing else from this pattern, remember: Jenkins configuration as code lets you automate and version control your Jenkins setup using a simple YAML file.

Common Mistakes

Trying to apply JCasC configuration before Jenkins is fully started

Jenkins rejects configuration changes if the server is not ready, causing errors.

Wait until Jenkins logs show it is fully up before applying the configuration.

Using incorrect YAML indentation or syntax in the jenkins.yaml file

YAML parsing fails and Jenkins cannot apply the configuration.

Use a YAML validator and follow exact indentation rules to ensure valid syntax.

Not disabling the setup wizard when automating Jenkins startup

The setup wizard blocks automated configuration and requires manual input.

Start Jenkins with -Djenkins.install.runSetupWizard=false to skip the wizard.

Summary

Start Jenkins with admin user and disable setup wizard for automation.

Create a jenkins.yaml file describing your Jenkins settings in YAML format.

Apply the configuration using Jenkins Configuration as Code REST API.

Verify the applied configuration by exporting it back as YAML.

Practice

1. What is the main purpose of Jenkins Configuration as Code (JCasC)?

easy

A. To monitor Jenkins server performance

B. To write Jenkins plugins in Java

C. To define Jenkins setup using a YAML file for easy automation

D. To create Jenkins jobs manually through the UI

Solution

1. Step 1: Understand JCasC concept

   JCasC allows Jenkins setup to be described in a YAML file instead of manual UI steps.

2. Step 2: Identify the main benefit

   This YAML file makes automation, sharing, and repeating Jenkins setup easy and safe.

3. Final Answer:

   To define Jenkins setup using a YAML file for easy automation -> Option C

4. Quick Check:

   JCasC = YAML setup automation [OK]

Hint: JCasC means Jenkins setup in YAML file [OK]

Common Mistakes:

• Confusing JCasC with plugin development
• Thinking JCasC is for manual UI job creation
• Assuming JCasC monitors performance

2. Which of the following is the correct syntax to define Jenkins system message in a JCasC YAML file?

easy

A. jenkins:
systemMessage: "Welcome to Jenkins!"

B. jenkins:
system_message: "Welcome to Jenkins!"

C. jenkins:
system-message: "Welcome to Jenkins!"

D. jenkins:
system message: "Welcome to Jenkins!"

Solution

1. Step 1: Check YAML key naming conventions

   JCasC uses camelCase keys matching Jenkins config names, so 'systemMessage' is correct.

2. Step 2: Validate YAML syntax

   jenkins: systemMessage: "Welcome to Jenkins!" uses correct key and proper YAML indentation and quotes.

3. Final Answer:

   jenkins:\n systemMessage: "Welcome to Jenkins!" -> Option A

4. Quick Check:

   Correct key is systemMessage in YAML [OK]

Hint: Use camelCase keys exactly as Jenkins expects [OK]

Common Mistakes:

• Using underscores instead of camelCase
• Using spaces or dashes in keys
• Incorrect YAML indentation

3. Given this JCasC snippet, what will be the Jenkins admin username after applying it?

jenkins:
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "admin"
          password: "admin123"

medium

A. root

B. user

C. guest

D. admin

Solution

1. Step 1: Read the users list in securityRealm

   The YAML defines one user with id 'admin' and password 'admin123'.

2. Step 2: Identify the admin username

   The user id 'admin' is the admin username set by this config.

3. Final Answer:

   admin -> Option D

4. Quick Check:

   User id in YAML = admin [OK]

Hint: Look for 'id' under users in securityRealm [OK]

Common Mistakes:

• Assuming default username instead of YAML value
• Confusing password with username
• Ignoring YAML indentation and structure

4. You applied this JCasC YAML but Jenkins failed to start:

jenkins:
  systemMessage "Hello Jenkins!"

What is the error in this configuration?

medium

A. Incorrect indentation of systemMessage

B. Missing colon ':' after systemMessage key

C. systemMessage should be under securityRealm

D. Quotes around Hello Jenkins! are not allowed

Solution

1. Step 1: Check YAML key-value syntax

   YAML requires a colon ':' after keys to separate them from values.

2. Step 2: Identify missing colon

   The line 'systemMessage "Hello Jenkins!"' misses the colon after systemMessage.

3. Final Answer:

   Missing colon ':' after systemMessage key -> Option B

4. Quick Check:

   YAML key:value needs colon [OK]

Hint: YAML keys must have colon ':' before values [OK]

Common Mistakes:

• Forgetting colon after key
• Misplacing keys under wrong parent
• Thinking quotes are forbidden

5. You want to automate Jenkins setup with JCasC to create two users: 'alice' and 'bob'. Which YAML snippet correctly defines both users with passwords?

hard

A. jenkins:
securityRealm:
local:
allowsSignup: false
users:
- id: "alice"
password: "alicePass"
- id: "bob"
password: "bobPass"

B. jenkins:
securityRealm:
local:
allowsSignup: false
users:
id: "alice"
password: "alicePass"
id: "bob"
password: "bobPass"

C. jenkins:
securityRealm:
local:
allowsSignup: false
users:
alice: "alicePass"
bob: "bobPass"

D. jenkins:
securityRealm:
local:
allowsSignup: false
users:
- alice: "alicePass"
- bob: "bobPass"

Solution

1. Step 1: Understand users list format

   Users must be a list of maps with 'id' and 'password' keys for each user.

2. Step 2: Check each option's structure

   jenkins: securityRealm: local: allowsSignup: false users: - id: "alice" password: "alicePass" - id: "bob" password: "bobPass" correctly uses a list with '- id' and 'password' pairs for alice and bob.

3. Final Answer:

   jenkins:\n securityRealm:\n local:\n allowsSignup: false\n users:\n - id: "alice"\n password: "alicePass"\n - id: "bob"\n password: "bobPass" -> Option A

4. Quick Check:

   Users list with id/password pairs = jenkins: securityRealm: local: allowsSignup: false users: - id: "alice" password: "alicePass" - id: "bob" password: "bobPass" [OK]

Hint: Users must be list items with id and password keys [OK]

Common Mistakes:

• Defining users as a map instead of list
• Repeating keys without list dash
• Using username as key instead of id