Skip to content

Jenkins Configuration as Code (JCasC)

Jenkins Configuration as Code (JCasC) is a Jenkins plugin and methodology that allows administrators to define and manage the Jenkins configuration externally using YAML files, rather than manually configuring settings through the user interface^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]. This approach enables version-controlled, reproducible Jenkins deployments^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

In the context of the official Jenkins Helm chart, JCasC is enabled by default^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__VALUES_SUMMARY.md] and is configured by passing values to the controller via the controller.JCasC key^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

Custom Configuration Scripts

Administrators can specify custom configuration scripts by adding sub-keys to controller.JCasC.configScripts^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

  • Key Naming: The sub-keys used before the pipe | character act as labels for the configuration section. These labels must conform to RFC 1123 DNS label definitions, meaning they should contain only lowercase alphanumeric characters or hyphens^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].
  • File Generation: Each defined key is generated as a separate YAML configuration file. By default, these files are stored in the /var/jenkins_home/casc_configs directory on the Jenkins controller^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].
  • Content Structure: The content provided after the | character becomes the body of the YAML file. This content typically starts with a JCasC root element such as jenkins, credentials, or securityRealm^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

Example: Configuring a System Message

controller:
  JCasC:
    configScripts:
      welcome-message: |
        jenkins:
          systemMessage: Welcome to our CI\CD server.
^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]

Security Realm and Authorization

The Helm chart utilizes JCasC to define the security realm and authorization strategy for the Jenkins instance^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

A default configuration is provided that creates a single administrative user. This user's credentials are configured via chart-admin-username and chart-admin-password^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]. By default, this setup allows any logged-in user to perform any action while denying anonymous read access^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]. For production environments, it is recommended to adjust these settings to use more robust strategies such as LDAP, OIDC, or a globalMatrix authorization strategy^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

Configuration Constraints and Overrides

JCasC configurations supplied via configScripts cannot override settings that are already defined by the chart's default configuration files^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]. Attempting to do so will result in a conflicting configuration error^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

For example, specific settings such as the Jenkins URL and System Admin email address must be configured using top-level Helm values rather than through JCasC scripts^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

Incorrect Approach (using JCasC): 

controller:
  JCasC:
    configScripts:
      jenkins-url: |
        unclassified:
          location:
            url: https://example.com/jenkins

Correct Approach (using Helm values): 

controller:
  jenkinsUrl: https://example.com/jenkins
  jenkinsAdminEmail: example@mail.com
^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]

Auto-Reload Configuration

Changes made to JCasC scripts can be applied either by restarting the Jenkins Pod (which is the default behavior) or via on-the-fly auto-reload^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

To enable auto-reload, the value controller.sidecars.configAutoReload.enabled must be set to true^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__VALUES_SUMMARY.md]. This configuration installs a sidecar container (default image: kiwigrid/k8s-sidecar) that watches for configuration changes and issues a reload request to the Jenkins instance automatically[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md][400-devops__06-Kubernetes__devops-helm__helm-jenkins__VALUES_SUMMARY.md].

RBAC Requirement: If auto-reload is enabled, Role-Based Access Control (RBAC) must be created by setting rbac.create: true^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]. This grants the sidecar container the necessary permissions to watch the ConfigMaps for changes^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

controller:
  sidecars:
    configAutoReload:
      enabled: true
rbac:
  create: true
^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]

Using Secrets in JCasC

JCasC supports referencing Kubernetes Secrets, which allows sensitive data—such as credentials or API keys—to be kept out of standard configuration files^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

Secrets can be mounted into the controller using controller.additionalSecrets or controller.additionalExistingSecrets^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]. Once mounted, these values can be referenced within JCasC using variable substitution.

Example: Referencing Secrets 

controller:
  JCasC:
    securityRealm: |
      oic:
        clientId: ${client_id}
        clientSecret: ${client_secret}
^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md]

Secrets from HashiCorp Vault

The Helm chart also supports generating SecretClaim resources via the controller.secretClaims parameter^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__VALUES_SUMMARY.md]. This feature enables the automatic creation of Kubernetes Secrets from HashiCorp Vault using the kube-vault-controller^[400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md].

Sources

  • 400-devops__06-Kubernetes__devops-helm__helm-jenkins__README.md
  • 400-devops__06-Kubernetes__devops-helm__helm-jenkins__VALUES_SUMMARY.md