Using Configuration as Code (JCasC)

1. Understanding JCasC Concept

Jenkins Configuration as Code (JCasC) is a plugin that allows you to define Jenkins configuration in code using YAML format. This approach enables version-controlled, reproducible, and declarative management of Jenkins settings.

Feature	Description	Status
Declarative Configuration	Configuration defined in YAML files instead of the Jenkins UI	NEW
Version Control	Configuration can be stored in Git or other version control systems	NEW
Reproducibility	Same configuration can be applied to multiple Jenkins instances	NEW
Plugin Support	Supports configuration of plugins and their settings	NEW

Example: Basic JCasC Configuration

jenkins:
  systemMessage: "Welcome to Jenkins Configuration as Code"
  numExecutors: 2
  nodes:
    - permanent:
        name: "agent1"
        remoteFS: "/home/jenkins"
        launcher:
          jnlp:
            workDirSettings:
              disabled: false
              internalDir: "remoting"

Note: JCasC is available as a plugin and requires Jenkins 2.303 or later.

2. Creating jenkins.yaml Configuration

Example: Basic Jenkins Configuration

jenkins:
  systemMessage: "Welcome to Jenkins Configuration as Code"
  numExecutors: 2
  labelString: "master"
  mode: EXCLUSIVE
  nodeProperties:
    - envVars:
        env:
          - key: "ENV_VAR"
            value: "value"

Property	Description	Values
jenkins.systemMessage	System message displayed on Jenkins dashboard	`string`
jenkins.numExecutors	Number of executors to run in parallel	`integer`
jenkins.labelString	Label to assign to the master node	`string`
jenkins.mode	Node mode (EXCLUSIVE or NORMAL)	`EXCLUSIVE`, `NORMAL`

Note: The jenkins.yaml file should be placed in the JENKINS_HOME/casc_configs/ directory.

Warning: Ensure that all plugins required by the configuration are installed before applying the jenkins.yaml.

3. Configuring System Settings via YAML

Property	Values	Description
jenkins	`object`	Root object for Jenkins configuration
jenkins.systemMessage	`string`	System message displayed on Jenkins dashboard
jenkins.httpPort	`int`	HTTP port Jenkins listens on (default: 8080)
jenkins.httpsPort	`int`	HTTPS port Jenkins listens on (default: -1)
jenkins.installWizard	`boolean`	Whether to show the installation wizard on first startup
jenkins.adminUser	`object`	Configuration for admin user (username, password)

Example: Basic Jenkins System Configuration

jenkins:
  systemMessage: "Welcome to Jenkins CI/CD"
  httpPort: 8080
  httpsPort: -1
  installWizard: false
  adminUser:
    username: "admin"
    password: "secret123"

Note: The adminUser configuration is only used during initial setup. For existing installations, use the Jenkins UI or API to manage users.

4. Managing Plugins via JCasC

Property	Values	Description
plugins	`list<Plugin>`	List of plugins to manage via JCasC

Example: Plugin Management Configuration

plugins:
  - name: "workflow-aggregator"
    version: "2.6"
  - name: "git"
    version: "4.10.1"

Note: Plugin versions are managed by JCasC and will be installed or updated accordingly.

Plugin Field	Values	Description
name	`string`	Name of the Jenkins plugin (e.g., `workflow-aggregator`)
version	`string`	Version of the plugin to install (e.g., `2.6`)

Warning: Ensure plugin versions are compatible with your Jenkins version to avoid runtime issues.

Plugin Management Best Practices

Use specific plugin versions to ensure reproducibility.
Validate plugin dependencies before applying configuration.
Use plugins block to declaratively manage Jenkins plugins.

5. Configuring Security via JCasC

Property	Values	Description
securityRealm	`ldap`, `activeDirectory`, `jenkins`	Defines how users are authenticated
authorizationStrategy	`roleBased`, `matrixBased`	Defines how users are authorized to perform actions

Example: LDAP Security Configuration

securityRealm:
  ldap:
    server: "ldap.example.com"
    rootDN: "dc=example,dc=com"
    userSearchBase: "ou=people"
    userSearchFilter: "(uid={0})"
    groupSearchBase: "ou=groups"
    groupSearchFilter: "(member={0})"
    managerPasswordSecret: "secret"
authorizationStrategy:
  roleBased:
    roles:
      - name: "admin"
        permissions:
          - "hudson.model.Hudson.Administer"
      - name: "developer"
        permissions:
          - "hudson.model.Item.Read"
          - "hudson.model.Item.Build"

Note: Ensure the managerPasswordSecret is properly secured and not exposed in plain text.

Warning: Misconfiguring security can lead to unauthorized access. Always test configurations in a staging environment before applying to production.

6. Managing Credentials via JCasC

Property	Values	Description
credentials	`string`	Defines the credential ID used in Jenkins configuration
scope	`GLOBAL` or `SYSTEM`	Scope of the credential, either global or system-wide
username	`string`	Username for the credential (e.g., for username/password)
password	`string`	Password for the credential (encrypted in JCasC)
description	`string`	Description of the credential for documentation purposes

Example: Defining a Username/Password Credential

credentials:
  system:
    - usernamePassword:
        id: "my-credential"
        scope: "GLOBAL"
        username: "admin"
        password: "secret123"
        description: "Admin credentials for external API"

Example: Defining a SSH Private Key Credential

credentials:
  system:
    - sshUserPrivateKey:
        id: "ssh-key"
        scope: "GLOBAL"
        username: "jenkins"
        privateKey: |
          -----BEGIN RSA PRIVATE KEY-----
          MIIEowIBAAKCAQEA...
          -----END RSA PRIVATE KEY-----
        description: "SSH key for deployment"

Note: Credentials defined via JCasC are stored in the credentials.xml file and can be managed through Jenkins UI or API.

Warning: Ensure that sensitive credential values (e.g., passwords) are encrypted or stored securely when using JCasC.

7. Validating Configuration Files

Example: Validate Jenkins Configuration

curl -X POST "http://jenkins.example.com/configuration-as-code/validate" \
  -H "Content-Type: text/yaml" \
  -d @jenkins.yaml

Option	Values	Description
validate	`POST /configuration-as-code/validate`	Endpoint to validate JCasC YAML configuration
content-type	`text/yaml`	Required MIME type for configuration input

Note: Validation does not apply changes to the Jenkins instance.

Warning: Invalid configurations may cause Jenkins to fail to start or behave unexpectedly.

8. Applying Configuration Changes

Example: Apply JCasC configuration via UI

curl -X POST "http://jenkins.example.com/configuration-as-code/reload" \
  -H "Authorization: Basic base64encodedcredentials"

Method	Description	Notes
POST /configuration-as-code/reload	Triggers a reload of the JCasC configuration	Requires admin privileges
GET /configuration-as-code/status	Checks the status of JCasC configuration	Returns current configuration state

Note: Changes made through the UI or API will be applied immediately if valid.

Warning: Invalid configurations may cause Jenkins to fail to start or behave unexpectedly.

Configuration Reload Process

Jenkins validates the new configuration before applying it
Any validation errors will be logged and prevent reload
Successful reload updates all Jenkins components dynamically

9. Exporting Existing Configuration

Exporting existing Jenkins configuration allows you to capture the current state of your Jenkins instance in a format that can be version-controlled and reused.

Method	Description	Notes
Jenkins REST API	Use the `/api/json` endpoint to retrieve configuration data.	Requires appropriate permissions and may expose sensitive information.
JCasC Plugin	Install and configure the `Configuration as Code` plugin to export configurations.	Exports configuration in YAML format, suitable for version control.
CLI Tool	Use the Jenkins CLI to export configurations via command-line tools.	Can be automated in scripts and supports various export formats.

Example: Exporting via JCasC Plugin

jenkins:
  systemMessage: "Welcome to Jenkins"
  numExecutors: 2
  nodes:
    - permanent:
        name: "agent-1"
        remoteFS: "/home/jenkins"
        launcher:
          jnlp:
            workDir: "work"

Note: Ensure that sensitive data like credentials are properly secured or excluded from the exported configuration.

Warning: Exported configurations may contain sensitive information. Always review and sanitize before committing to version control.

10. Using Environment Variables in JCasC

Variable	Type	Description	Usage Example
JENKINS_URL	`string`	URL of the Jenkins instance	`jenkins: url: ${JENKINS_URL}`
JENKINS_HOME	`string`	Home directory of Jenkins	`jenkins: home: ${JENKINS_HOME}`
JAVA_HOME	`string`	Java Home directory path	`jenkins: jvmOptions: -Djava.home=${JAVA_HOME}`
BUILD_NUMBER	`integer`	Current build number in pipeline	`pipeline: stages: - stage: name: "Build" steps: - echo "Build #${BUILD_NUMBER}"`
JOB_NAME	`string`	Name of the current job	`job: name: ${JOB_NAME}`

Example: Setting Jenkins URL from Environment Variable

jenkins:
  url: ${JENKINS_URL}
  systemMessage: "Running on Jenkins instance at ${JENKINS_URL}"

Note: Environment variables must be properly escaped in YAML files. Use ${VAR_NAME} syntax for variable substitution.

Warning: Ensure that environment variables are set in the Jenkins server's runtime context to avoid configuration errors.

11. Version Controlling Configuration

Aspect	Description	Best Practice
JCasC Configuration Files	`jenkins.yaml` or `jenkins.xml`	Store in version control systems like Git
File Format	YAML or XML	Use YAML for readability and maintainability
Version Control Integration	Git repositories with CI/CD pipelines	Automated deployment on commit to main branch

Example: Git Integration Setup

git init
git add jenkins.yaml
git commit -m "Initial JCasC configuration"
git remote add origin https://github.com/user/repo.git
git push -u origin main

Note: Ensure that sensitive data is not committed to version control. Use environment variables or secrets management tools.