Advanced CasC topics for controllers

Enabling HTTPS

The security token and Configuration as Code (CasC) for Controllers 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.

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!"

Advanced CasC topics for controllers

Enabling HTTPS

Example startup parameters

Using a self-signed certificate

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