Advanced CasC topics for controllers

Enabling HTTPS

The security token and Configuration as Code bundle both contain sensitive information, so it is recommended that they are protected by using HTTPS when sent between the operations center and controller. HTTPS must be enabled on the operations center side. Typically enabling HTTPS is done by terminating the secure connection externally in a reverse proxy, but it can also be terminated in the Jenkins server. To enable HTTPS, add startup parameters to specify the HTTPS port and a keystore containing server certificate and key.

Example startup parameters

java -jar jenkins.war --httpPort=-1 --httpsPort=8443 \
  --httpsKeyStore=path/to/keystore \
  --httpsKeyStorePassword=keystorePassword▼

Using a self-signed certificate

This configuration is not recommended and should not be used in production.

If you are using this method in a limited scope for test deployments, refer to Set-up SSL on a CJP environment with a self-sign SSL certificate on each Jenkins box, a CloudBees Knowledge Base article, for guidance on setting up CloudBees CI with a self-signed certificates.

Calculating plugin dependencies

The Plugin Installation Manager Tool can be used to assist with determining the full list of a plugin’s transitive dependencies. The tool takes as input a plugins.yaml that lists plugins you would like to install and outputs a list of all the plugins to be installed, along with all their transitive dependencies. This list can then be used to populate the plugin catalog so the plugins specified in plugins.yaml can be successfully installed.

The plugins.yaml file used by the tool is not the same as the one created previously when authoring the Configuration as Code bundle.

Prerequisites

The plugin.yaml file from the Configuration as Code bundle
Java Runtime Environment (JRE) or Java Developer Kit (JDK) installed and configured
Access to the jenkins.war file that will be used to create the connected controller

To create a list of plugins to be installed including all transitive dependencies:

Download the latest release of the Plugin Installation Manager Tool.

Using the plugins.yaml file from the Configuration as Code bundle, create a plugins.yaml file for use with the tool. Rename the Configuration as Code bundle’s plugins.yaml file’s YAML property id to artifactId as illustrated below:

plugins.yaml from Configuration as Code bundle plugins.yaml for use with tool

`plugins.yaml` from Configuration as Code bundle	`plugins.yaml` for use with tool
`plugins: - id: "git" - id: "maven-plugin"` ▼	`plugins: - artifactId: "git" - artifactId: "maven-plugin"` ▼

plugins:
  - id: "git"
  - id: "maven-plugin"▼

plugins:
  - artifactId: "git"
  - artifactId: "maven-plugin"▼

Run the tool, using the following command, updating it with the location of your controller .war file and the location of your plugins.yaml file:
```
java -jar jenkins-plugin-manager-*.jar \
--no-download --plugin-download-directory plugin-download \
--list \
--war $JENKINS_HOME/cloudbees-core-cm.war \(1)
--plugin-file plugins.yaml(2)▼
```
1 The location of the controller .war file.

2 The location of the plugins.yaml file.

Sample output file with list of plugins

File containing list of plugins to be downloaded: plugins.yaml
Reading in plugins from plugins.yaml

Plugin download location: plugin-download
No CLI option or environment variable set for update center, using default of https://updates.jenkins.io
No CLI option or environment variable set for experimental update center, using default of https://updates.jenkins.io/experimental
No CLI option or environment variable set for incrementals mirror, using default of https://repo.jenkins-ci.org/incrementals
Will use war file: $JENKINS_HOME/jenkins.war

Installed plugins:

Bundled plugins:

Set of all requested plugins:
chucknorris 1.2
workflow-step-api 1.14

Set of all requested plugins that will be downloaded:
chucknorris 1.2
workflow-step-api 1.14

Set of all existing plugins and plugins that will be downloaded:
chucknorris 1.2
workflow-step-api 1.14
Done▼

Find the section in your output titled Set of all requested plugins that will be downloaded. This section is the list of plugins that will need to be added to plugin-catalog.yaml to successfully install the plugins.yaml.

You may get significantly more output than the example, especially in the “Bundled Plugins” and “Set of all existing plugins and plugins that will be downloaded” sections.

Configuring bundle inheritance with CasC

You can simplify bundle composition and maintenance by creating a "child" bundle that inherits common configuration elements from a "parent" bundle. In one parent bundle, you can maintain common configuration elements that are automatically inherited by all bundles in the inheritance chain, which eliminates the need to maintain and update individual bundles.

To configure bundle inheritance, you must add a parent property to the child bundle’s bundle.yaml file and specify the parent bundle’s folder name as the value for the parent property.

Child bundles must only contain configuration elements that are unique to that bundle and should not overwrite the parent bundle’s configuration elements. Once the parent bundle and child bundle are configured, the YAML files in the parent and child bundles are processed as follows:

Jenkins Configuration as Code files are processed using the rules defined by the Jenkins Configuration as Code plugin.
If a plugins.yaml file is present in both the parent and child bundle, the parent and child plugins.yaml files are merged.
If a plugin-catalog.yaml file is present in both the parent and child bundle, the plugin-catalog.yaml in the child bundle is processed and the plugin-catalog.yaml in the parent bundle is ignored.
items.yaml files are processed one-by-one. The parent bundle is processed first, followed by the child bundle.
rbac.yaml files are processed one-by-one. The parent bundle is processed first, followed by the child bundle.
If a variables.yaml file is present in both the parent and child bundles, the parent and child variables.yaml files are both processed. If the same variable name exists in both variables.yaml files, the variable in the child bundle’s variables.yaml file overrides the variable in the parent bundle’s variables.yaml file.

If making a change to a bundle, do not apply the change to all controllers at once. Instead, apply the change to a single controller-specific bundle, verify it works as expected, and then apply the change to all bundles.

Example bundle inheritance

In this example, there is a parent bundle: bundle-global. There are also two child bundles: bundle-1 and bundle-2. The child bundles use the same jenkins.yaml file and plugins.yaml file as the parent bundle but include unique items in their items.yaml files.

/oc-bundles
├── bundle-global
│   ├── bundle.yaml
│   ├── jenkins.yaml
│   ├── plugins.yaml
│   └── items.yaml
├── bundle-1
│   ├── bundle.yaml
│   └── items.yaml
└── bundle-2
    ├── bundle.yaml
    └── items.yaml▼

`bundle-global` example

Within bundle-global, the bundle.yaml file defines:

The bundle’s unique id: "bundle-global".
The contents of the bundle: a jenkins.yaml file, plugins.yaml file, and items.yaml file.

id: "bundle-global"
version: "1"
apiVersion: "1"
description: "CasC parent bundle with common configuration elements"
jcasc:
  - "jenkins.yaml"
plugins:
  - "plugins.yaml"
items:
  - "items.yaml"▼

bundle-global includes a jenkins.yaml file that describes the controller:

jenkins:
  systemMessage: "Controller configured using CloudBees CasC"
  numExecutors: 0
  securityRealm:
    ldap:
      configurations:
      - displayNameAttributeName: "cn"
        groupMembershipStrategy:
          fromGroupSearch:
            filter: "member={0}"
        groupSearchBase: "ou=Groups"
        inhibitInferRootDN: false
        managerDN: "cn=admin,dc=example,dc=org"
        managerPasswordSecret: ${LDAP_MANAGER_PASSWORD}
        rootDN: "dc=example,dc=org"
        server: "ldap://ldap-openldap:389"
        userSearchBase: "ou=People"
      disableMailAddressResolver: false
      groupIdStrategy: "caseInsensitive"
      userIdStrategy: "caseInsensitive"
  authorizationStrategy: "cloudBeesRoleBasedAccessControl"▼

bundle-global includes a plugins.yaml file that contains a list of all plugins to install on the controller:

plugins:
  # In CloudBees Assurance Program (CAP)
  - id: "bitbucket-branch-source"
  - id: "branch-api"
  - id: "cloudbees-casc-client"
  - id: "cloudbees-casc-items-api"
  - id: "cloudbees-casc-items-commons"
  - id: "cloudbees-casc-items-controller"
  - id: "cloudbees-template"
  - id: "cloudbees-workflow-template"
  - id: "configuration-as-code"
  - id: "git"
  - id: "github-branch-source"
  - id: "infradna-backup"
  - id: "workflow-multibranch"
  # Not in CAP (see plugin-catalog.yaml)
  - id: "manage-permission"▼

bundle-global includes an items.yaml file that contains the required removeStrategy properties and the root property that defines the root folder path for item creation.

removeStrategy:
  items: "none"
  rbac: "sync"

root: "/projects"▼

`bundle-1` example

Within bundle-1, the bundle.yaml file defines:

The bundle’s unique id: "bundle-1".
The parent bundle to inherit from: "bundle-global".
The contents of the bundle that are unique to the child bundle. bundle-1 requires additional folders that are not included in the bundle-global parent bundle. Therefore, the items.yaml file must be added, since it is unique to bundle-1.

id: "bundle-1"
version: "1"
apiVersion: "1"
description: "CasC child bundle 1"
parent: "bundle-global"
items:
  - "items.yaml"▼

bundle-1 includes an items.yaml file that contains an additional folder and subfolders that should be created under the /projects folder path specified in bundle-global.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "folder"
    name: "project-alpha"
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    items:
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"▼

`bundle-2` example

Within bundle-2, the bundle.yaml file defines:

The bundle’s unique id: "bundle-2".
The parent bundle to inherit from: "bundle-global".
The contents of the bundle that are unique to the child bundle. bundle-2 requires an additional folder that is not included in the bundle-global parent bundle. Therefore, the items.yaml file must be added, since it is unique to bundle-2.

id: "bundle-2"
version: "1"
apiVersion: "1"
description: "CasC child bundle 2"
parent: "bundle-global"
items:
  - "items.yaml"▼

bundle-2 includes an items.yaml file that contains an additional folder that should be created under the /projects folder path specified in bundle-global.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"▼

1	The location of the controller `.war` file.
2	The location of the `plugins.yaml` file.

Advanced CasC topics for controllers

Enabling HTTPS

Example startup parameters

Using a self-signed certificate

Calculating plugin dependencies

Prerequisites

Sample output file with list of plugins

Configuring bundle inheritance with CasC

Example bundle inheritance

bundle-global example

bundle-1 example

bundle-2 example

`bundle-global` example

`bundle-1` example

`bundle-2` example