Repository files navigation

• Introduction
• Getting Started
• Examples and demos
• Handling Secrets
• Security considerations
• Exporting configurations
• Validating configurations
• Merge Strategy
• Triggering Configuration Reload
• Installing plugins
• Supported Plugins
• Adding JCasC support to a plugin
• Configuration-as-Code extension plugins
• Jenkins Enhancement Proposal

Setting up Jenkins is a complex process, as both Jenkins and its plugins require some tuning and configuration,with dozens of parameters to set within the web UImanage section.

Experienced Jenkins users rely on groovy init scripts to customize Jenkins and enforce the desired state. Thosescripts directly invoke Jenkins API and, as such, can do everything (at your own risk). But they also requireyou to know Jenkins internals and are confident in writing groovy scripts on top of Jenkins API.

The Configuration as Code plugin is anopinionated way to configure Jenkins based onhuman-readable declarative configuration files. Writing such a file should be feasible without being a Jenkinsexpert, just translating intocode a configuration process one is used to executing in the web UI.

The below configuration file includes root entries for various components of your primary Jenkins installation. Thejenkins one is for the root Jenkins object, and the other ones are for different global configuration elements.

jenkins:systemMessage:"Jenkins configured automatically by Jenkins Configuration as Code plugin\n\n"globalNodeProperties:  -envVars:env:      -key:VARIABLE1value:foo      -key:VARIABLE2value:barsecurityRealm:ldap:configurations:        -groupMembershipStrategy:fromUserRecord:attributeName:"memberOf"inhibitInferRootDN:falserootDN:"dc=acme,dc=org"server:"ldaps://ldap.acme.org:1636"nodes:    -permanent:name:"static-agent"remoteFS:"/home/jenkins"launcher:inbound:workDirSettings:disabled:truefailIfWorkDirIsMissing:falseinternalDir:"remoting"workDirPath:"/tmp"slaveAgentPort:50000tool:git:installations:      -name:githome:/usr/local/bin/gitcredentials:system:domainCredentials:      -credentials:          -basicSSHUserPrivateKey:scope:SYSTEMid:ssh_with_passphrase_providedusername:ssh_rootpassphrase:${SSH_KEY_PASSWORD}description:"SSH passphrase with private key file. Private key provided"privateKeySource:directEntry:privateKey:${SSH_PRIVATE_KEY}

Additionally, we want to have a well-documented syntax file and tooling to assist in writing and testing,so end users have full guidance in using this toolset and do not have to search for examples on the Internet.

See thepresentation slides from DevOps World - Jenkins World 2018 for an overview.

First, start a Jenkins instance with theConfiguration as Code plugin installed.

• Those running Jenkins as aDocker container (and maybe alsopre-installing plugins), do includeConfiguration as Code plugin.

Second, the plugin looks for theCASC_JENKINS_CONFIG environment variable. The variable points to a comma-separated list of any of the following:

• Path to a folder containing a set of config files. For example,/var/jenkins_home/casc_configs.
• A full path to a single file. For example,/var/jenkins_home/casc_configs/jenkins.yaml.
• A URL pointing to a file served on the web. For example,https://acme.org/jenkins.yaml.

If an element ofCASC_JENKINS_CONFIG points to a folder, the plugin will recursively traverse the folder to find file(s) with .yml,.yaml,.YAML,.YML suffix. It will exclude hidden files or files that contain a hidden folder inany part of the full path. It follows symbolic links for both files and directories.

All configuration files that are discovered MUST be supplementary. They cannot overwrite each other's configuration values. This creates a conflict and raises aConfiguratorException. Thus, the order of traversal does not matter to the final outcome.

Instead of setting theCASC_JENKINS_CONFIG environment variable, you can also define usingthecasc.jenkins.config Java property. This is useful when installing Jenkins via a packagemanagement tool and can't set an environment variable outside of a package-managed file, which couldbe overwritten by an update. For RHEL/CentOS systems, you can append the following to theJENKINS_JAVA_OPTIONS entry in/etc/sysconfig/jenkins

-Dcasc.jenkins.config=/jenkins/casc_configs

If you do not set theCASC_JENKINS_CONFIG environment variable or thecasc.jenkins.config Javaproperty, the plugin will default to looking for a single config file in$JENKINS_HOME/jenkins.yaml.

If set up correctly, you should be able to browse the Configuration as Code pageManage Jenkins ->Configuration as Code.

When configuring the first Jenkins instance, browse the examples shown in thedemosdirectory of this repository. If you have a plugin that does not have an example, consult the referencehelp document. Click theDocumentation link at the bottom of the Configuration as Code page in your Jenkins instance.

If you want to configure a specific plugin, search the page for the name of the plugin. The page willshow you which root element belongs to the configuration. Most installed plugins belong under theunclassified rootelement.

Seedemos folder with various samples.

Replace user interface based configuration for LDAP with the text-based configuration.

jenkins:securityRealm:ldap:configurations:        -groupMembershipStrategy:fromUserRecord:attributeName:"memberOf"inhibitInferRootDN:falserootDN:"dc=acme,dc=org"server:"ldaps://ldap.acme.org:1636"

Replace repeated elements with yaml anchors.Anchor keys must be prefixed withx- due to JCasC handling unknown root elements.

x-jenkins-linux-node:&jenkins_linux_node_anchorremoteFS:"/home/jenkins"launcher:inbound:workDirSettings:disabled:truefailIfWorkDirIsMissing:falseinternalDir:"remoting"workDirPath:"/tmp"jenkins:nodes:    -permanent:name:"static-agent1"<<:*jenkins_linux_node_anchor    -permanent:name:"static-agent2"<<:*jenkins_linux_node_anchor

Which produces two permanent agent nodes which can also be written like this.

jenkins:nodes:    -permanent:name:"static-agent1"remoteFS:"/home/jenkins"launcher:inbound:workDirSettings:disabled:truefailIfWorkDirIsMissing:falseinternalDir:"remoting"workDirPath:"/tmp"    -permanent:name:"static-agent2"remoteFS:"/home/jenkins"launcher:inbound:workDirSettings:disabled:truefailIfWorkDirIsMissing:falseinternalDir:"remoting"workDirPath:"/tmp"

Only Jenkins administrators are able to create or update a Jenkins instance using configuration as code configuration files.However, in some environments, administrators may choose to allow less privileged users to modify portions of the configuration files, for example by storing them in an SCM repository that those users have access to.Allowing non-administrators to edit these configuration files can pose various security risks, so any changes made by non-administrators must be reviewed for safety before they are applied.

Here are some examples of changes that could be problematic:

• Modification of the security realm or authorization strategy settings could give users higher permissions than intended.
• Interpolation of secrets in unprotected contexts may expose sensitive data. For example, a snippet likesystemMessage: "${SENSITIVE_VARIABLE}" could expose the value of a sensitive environment variable to all users who are able to access Jenkins.

We don't support installing plugins with JCasC, so you need to use something else for this,

Dockers users can use:
https://github.com/jenkinsci/docker/#preinstalling-plugins

Kubernetes users:
https://github.com/jenkinsci/helm-charts

Most plugins should be supported out-of-the-box or maybe require some minimal changes. See thisdashboard for known compatibility issues.

Plugin developers wanting to support JCasC in their plugin shouldcheck out our how-to guide.

• configuration-as-code-groovy-plugin
  Allows specifying groovy code that should run on during configuration.

As configuration as code is demonstrated to be a highly requested topic in the Jenkins community, we have publishedJEP 201 as a proposal to make this a standard componentof the Jenkins project. The proposal was accepted. 🎉