Creating a CasC bundle for controllers

The configuration of a controller is described in a collection of YAML files referred to as a Configuration as Code bundle. The operations center can store many different configuration bundles representing a selection of predefined controllers. Configuration bundles are stored securely on the operations center server which manages the secure distribution of the Configuration as Code bundles to the correct controllers.

Manually creating a configuration bundle

To create a new configuration bundle, create each of the files listed below. A CasC bundle consists of the following files:

bundle.yaml: This file is an index file that describes the bundle, and references the other files in the bundle.
jenkins.yaml: This file contains the Jenkins configuration, as defined by the Configuration as Code plugin.
plugins.yaml: (Optional) This file contains a list of all plugins that should be installed.
plugin-catalog.yaml: (Optional) This file contains the plugin catalog definitions that should be created on the controller.
items.yaml: (Optional) This file contains the items to be created.
rbac.yaml: (Optional) This file contains all Role-Based Access Control (RBAC) groups and roles defined at the root level.
variables.yaml: (Optional) This file defines the variables that can be used in the jenkins.yaml, items.yaml, and rbac.yaml files.

For the bundle to be valid, the above files must use these exact filenames.
Any property not set in a bundle is created with a default value based on the plugins implemented for CasC. The default values can be:
- Null
- Empty lists
- A default value of the Java type. For example, a default integer would be 0.
- A specific value set for a property. For example, a default integer set to 1 instead of 0.

You can have a configuration bundle without the optional files. If you do not include these files in your bundle, they should not be listed in your bundle.yaml file.

The items.yaml and rbac.yaml files are only available in CloudBees CI release 2.249.3.1 or later.

bundle.yaml

The bundle.yaml file is an index file that describes the bundle and references the other files in the bundle. It can also be used to optionally configure bundle inheritance and bundle availability.

Property Type Description

string

Required. This bundle’s unique identifier.

The id property is a legacy property that is no longer used. However, it must be included in the bundle.yaml file for backward compatibility.

version

string

Required. The bundle’s version. If a controller is configured with a bundle using the -Dcore.casc.config.bundle=/path/to/casc-bundle Java system property, this value should be incremented whenever the bundle is modified.

When the operations center generates an effective bundle (after calculating inheritance) for a controller, the version attribute is the checksum of the entire bundle.

apiVersion

string

Required. This is the bundle’s API version. Valid values are apiVersion:1, and apiVersion:2 for CasC plugin management 2.0; otherwise, the bundle would be invalid.

Changes in the apiVersion values must be done with caution, as your CasC bundle may become invalid when updating this value. To understand these risks, refer to Risk while updating your CasC bundle. To learn more about how this property affects plugin management with CasC bundles, refer to Plugin management with CasC.

description

string

Optional. A helpful description of the bundle.

parent

string

Optional. The parent bundle’s unique folder name. This property provides bundle inheritance for CasC bundles that are added to the operations center using the CasC bundle location. This property is not supported if using an HTTP API endpoint or a CLI command to upload a bundle to the operations center.

With branch and tag support, the value of the parent property can be specified in two ways. For example, assume you have two branches, main and staging. A child bundle is contained in the main branch and a global bundle in both the main and staging branches. The parent value could be specified as follows:

parent: global: This property does not specify a branch. However, because the child bundle is in the main branch, CasC searches for the parent (global) bundle within in the same branch.
parent: main/global: This property value identifes the branch (main). Therefore, CasC searches for the parent bundle in the main branch.
parent: staging/global: This property value identifes the staging branch. Therefore, CasC searches for the parent bundle (global) within the staging branch.

For more information, refer to Configuring bundle inheritance with CasC.

allowCapExceptions

boolean

Optional. Allows Beekeeper plugin exceptions in the controller’s plugin-catalog.yaml file. For more information, refer to plugin-catalog.yaml and Beekeeper plugin exceptions.

true: Beekeeper plugin exceptions are allowed.
false: (default): Beekeeper plugin exceptions are not allowed.

availabilityPattern

string

Optional. Specifies the regex availability pattern, to define the full path to one or more controllers in the operations center that can use the CasC bundle. This property provides bundle availability for CasC bundles that are added to the operations center using the CasC bundle location, and is not supported if using an HTTP API endpoint or a CLI command to upload a bundle to the operations center. For more information, refer to Configuring bundle availability for controllers.

jcasc

list of strings

Optional. This indicates the bundle contains a jenkins.yaml file.

jcascMergeStrategy

string

Optional. Defines the merge strategy when multiple Jenkins Configuration as Code files are included in a CasC bundle. For more information, refer to Merge Strategy.

errorOnConflict: (default) Returns an exception if there is a conflict in multiple YAML files.
override: Overrides the configuration files according to the loading order. This indicates the bundle contains a jenkins.yaml file.

plugins

list of strings

Optional. This indicates the bundle contains a plugins.yaml file.

catalog

list of strings

Optional. This indicates the bundle contains a plugin-catalog.yaml file.

items

list of strings

Optional. This indicates the bundle contains a items.yaml file.

itemRemoveStrategy

object

Optional. This property is composed of the removeStrategy for items and the removeStrategy for groups created at the item level.

The itemRemoveStrategy can be specified in the bundle.yaml file and it applies to every item.yaml file in that bundle.
In the bundle.yaml file, itemRemoveStrategy prevails over the removeStrategy defined in the items.yaml.

This property has two sub-elememts: items and rbac. Valid values for these sub-elements are:

items
- none Creates items that do not exist in the instance or updates existing items with the values from the YAML file. Items not declared in the items.yaml file remain as is on the controller or in the operations center.
- sync: Deletes CasC supported items not defined in the items.yaml file. Items in the items.yaml continue in the same way as the none/update strategy.
- remove-supported: Deletes all CasC supported items in the instance and restarts the item creation with the updated bundle.
- remove-all: Deletes all items in the instance and restarts item creation.
rbac The values for this sub-property only apply on groups created for items and not for general groups.
- sync: If the groups already exist but the configuration changes, the new configuration is applied to the groups created for items and the existing groups not present in the new configuration are deleted.
- update: If the groups already exist but the configuration changes, only the existing groups are updated and replaced with the new groups.

If the itemRemoveStrategy is declared, then the items and rbac sub-elements are required. The itemRemoveStrategy property prevails over the removeStrategy property in the items.yaml file.

rbac

list of strings

Optional. This indicates the bundle contains a rbac.yaml file.

rbacRemoveStrategy

object

Optional. Valid values for this property are:

sync: If the role or group already exists, it is updated with the new configuration.
update: If the role or group already exists but the configuration changes, the existing role or group is updated and replaced with the new role or group.

The rbacRemoveStrategy property defined in the bundle.yaml prevails over removeStrategy in the rbac.yaml file.

Example bundle.yaml file

id: "remove-bundle"
version: "1"
apiVersion: "1"
description: "CasC bundle with removeStrategy in descriptor"
allowCapExceptions: true
availabilityPattern: "folder1/.*"
parent: "bundle-global"
jcasc:
  - "jenkins.yaml"
jcascMergeStrategy: "errorOnConflict"
plugins:
  - "plugins.yaml"
catalog:
  - "plugin-catalog.yaml"
itemRemoveStrategy:
  items: "remove-all"
  rbac: "sync"
rbacRemoveStrategy: "sync"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"
variables:
  - "variables.yaml"▼

jenkins.yaml

This file is the main Configuration as Code configuration file that describes the controller. For more information on how to format this file, refer to the Jenkins Configuration-as-Code plugin documentation.

Example jenkins.yaml file

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"(1)
globalCloudBeesPipelineTemplateCatalog:(2)
  catalogs:
  - branchOrTag: "main"
    scm:
      git:
        credentialsId: "credentials-id"
        id: "cf504eg3-4y5d-34w2-97b1-2q7xt2nm9731"(3)
        remote: "git@github.com:company/project-alpha.git"
    updateInterval: "1d"▼

1	Required to use CloudBees RBAC configured using CasC.
2	Required if using CasC to create a job based on a Pipeline Template Catalog.
3	Required property that defines the unique ID for the SCM repository where the Pipeline Template Catalog is stored.

plugins.yaml

This file lists all of the plugins to be installed on the controller or the operations center.

The content in the file changes depending on the value of the apiVersion field.

For CasC bundles using apiVersion:1, this file should be a list of plugin IDs for CAP and non-CAP plugins to be installed.

For CasC bundles that use apiVersion:2, this file has a more complex structure and can include the following:

A list of plugin IDs for CAP plugins.
Non-CAP plugins, in three different ways:
- Using only the plugin ID if the Non-CAP plugin is downloaded from the CloudBees Update Center or using a plugin catalog.
- Using the plugin ID and a URL if the Non-CAP plugin is directly downloaded from an URL.
- Using the plugin ID, the groupId, the version, and the repositoyId if the Non-CAP plugin is downloaded from a Maven repository.

CloudBees CI ignores URLs and GAV coordinates for those plugins that are also part of the plugin-catalog.yaml file. In those cases, the configuration in plugins.yaml is ignored, and the configuration in plugin-catalog.yaml prevails.

Find many popular plugins and their IDs at the following sites:

For more information, review the Plugin management with CasC page.

plugin-catalog.yaml

This file contains the plugin catalog definitions that can be installed on the controller. The plugin catalog widens the scope of plugins beyond those defined by CloudBees Assurance Program (CAP). Because the plugins.yaml file only installs plugins within CAP, the plugins-catalog.yaml file can install plugins outside of CAP on the controller. An optional location can also be specified for plugins that are not available in the standard update centers. For more information on plugin catalogs, refer to Installing non-CAP plugins with plugin catalogs.

Plugins will not be actually installed to the controller unless they are listed in the plugins.yaml file. Transitive dependencies are not automatically added.

The plugin catalog feature can be also used separately (non-CasC) on CloudBees CI controllers as described in the documentation. However when using it inside a CasC bundle there are some limitations. For more information, refer to Plugin catalog limitations in CasC.

Example plugin-catalog.yaml file

type: "plugin-catalog"
version: "1" (1)
name: "my-plugin-catalog"
displayName: "My Plugin Catalog"
configurations:
  - description: "Extensions to CAP"
    includePlugins:
      manage-permission: (2)
        version: 1.0.1 (3)
      #my-custom-plugin:
        #url: http://www.example.org/jenkins-plugins/my-custom-plugin-1.2.3.hpi
    beekeeperExceptions:
      support-core:
        version: "2.70"▼

1	`version` (required) - must currently have the value 1, which defines the current metadata format for the plugin catalog.
2	Add the `manage-permission` plugin to enable the Overall/Manage permission.
3	Replace 1.0.1 with the most recent version.

items.yaml

The items.yaml file contains a list of items to create or update within the instance.

By default, items that are present on the instance in the UI but not included in the items.yaml file will remain. However, you can change this behavior using different RemoveStrategy options.
You must install the prerequisite CloudBees CI software and plugins based on the item type you are creating.
If you want to customize your items.yaml file using environment variables or using the variables.yaml file in your bundle, you must install the Jenkins Configuration-as-Code plugin.

For more information, refer to Creating items with CasC for controllers.

Property Type Description

removeStrategy

object

Optional. It specifies the strategy to be followed when you apply a new configuration to an existing instance.

The removeStrategy property is optional for the items.yaml file; however, it is required in the bundle.yaml file.

Valid values are:

none Creates items that do not exist in the instance or updates existing items with the values from the YAMLfile. Items not declared in the items.yaml file remain as is on the controller.
sync: Deletes CasC supported items not defined in the items.yaml file. Items in the items.yaml will continue in the same way as the none/update strategy.
remove-supported: Deletes all CasC supported items in the instance and restarts the item creation with the updated bundle.
remove-all: Deletes all items in the instance and recreates them based on the contents of the items.yaml.

If a removeStrategy option is not declared, the default option none is used. When a removeStategy is declared in the parent bundle but not the child bundle, the child bundle uses the removeStrategy of the parent. If both the parent and the child bundle declares a removeStrategy then the parent bundle uses the removeStrategy of the child bundle.
If the removeStrategy property is declared for the items.yaml file, the items and rbac properties should also be defined.

Property Type Description

items

string

Required. It specifies the strategy to be followed when you apply a new configuration to an existing instance.

Valid values for this property are:

none Creates items that do not exist in the instance or updates existing items with the values from the YAML file. Items not declared in the items.yaml file remain as is on the controller or in the operations center.
sync: Deletes CasC supported items not defined in the items.yaml file. Items in the items.yaml continue in the same way as the none/update strategy.
remove-supported: Deletes all CasC supported items in the instance and restarts the item creation with the updated bundle.
remove-all: Deletes all items in the instance and then creates the items defined in the items.yaml file.

Variable resolution is disabled by default. This prevents items that contain embedded variable expressions from being replaced during import or export.

Property Type Description

rbac

string

Required. Specifies how an existing configuration is handled when a new configuration is applied.

sync: If the role or group already exists but the configuration changes, the new configuration is applied and the existing groups or roles are deleted.
update: If the role or group already exists but the configuration changes, only the existing role or group is updated and replaced with the new role or group.

Variable resolution is disabled by default. This prevents items that contain embedded variable expressions from being replaced during import or export.

root

string

Optional. Defines the root path for item creation. The path must already exist on the controller instance for the items to be successfully created. For more information, refer to Configuring bundle inheritance with CasC.

items

list of objects

Required. The list of items.

kind

string

Required. It defines the kind of item created. Supported items:

backupAndRestore
cloudbeesTemplatedJob
folder
freeStyle
multibranch
organizationFolder
pipeline

name

string

Required. The name of the item.

displayName

string

Optional. The display name of the item.

description

string

Optional. The description of the item.

groups

list of objects

Optional. The list of RBAC groups included in the item.

name

string

Required. The name of the group.

members

object

Required.

users

list of strings

Optional. A list of user ids of users that belong to the group.

roles

list

Required. A list of RBAC roles that are assigned to this group.

name

string

Required. The name of the assigned role.

filteredRoles

list of strings

Optional. The list of roles to filter.

Configure the `items.yaml` file to handle variable expressions

To escape variable expressions during an import, apply the cascItemsConfiguration to the CasC bundle or enable the setting on the System configuration page.

To configure the cascItemsConfiguration value in the items.yaml file:

unclassified:
  cascItemsConfiguration:
    variableInterpolationEnabledForAdmin: true (1)
    variableInterpolationEnabledForNonAdmin: true (2)▼

1	Set the value to `true` to allow administrators to use the variable resolution for items imported into the `items.yaml` file. The value is set to `false` by default.
2	Set the value to `true` to allow non-adminstrators to use the variable resolution for items imported into the `items.yaml` file. The value is set to `false` by default.

To configure CasC item configuration in the operations center:

From the dashboard, select Manage Jenkins System.
Navigate to CasC Items configuration.

Figure 1. Enable variable resolution
Select one of the following:
1. Enable or disable the variable resolution in the item creation for administrator: This allows administrators to use the variable resolution for items imported into the items.yaml file.
2. Enable or disable the variable resolution in the item creation for non-administrator: This allows non-administrators to use the variable resolution for items in the items.yaml file.
  
  These settings are disabled by default.
Select Save.

Example items.yaml file

If a CloudBees CI GitHub Organization is used to configure a repository from a GitHub Enterprise server and you add the server to the Configure System screen, API endpoint is a required field. You must verify that the apiUri property is configured in the items.yaml file. If the GitHub server is not an enterprise server, you can optionally remove the apiUri property from the items.yaml file.

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

items:
  - kind: "folder"
    name: project-${team_group}
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    properties:
      - folderCredentialsProperty:
          folderCredentials:
            - credentials:
                - usernamePassword:
                    password: ${secret_location}
                    scope: GLOBAL
                    description: description
                    id: test-id
                    usernameSecret: false
                    username: test-user
              domain: {}
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - ldap-project-${team_group}
        roles:
          - name: "developer"
    items:(1)
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles:(2)
      - "developer"
      - "browser"▼

1	Items can be nested within other items, enabling users to create a folder structure.
2	Roles can be filtered, for example to allow only administrators to view certain projects.

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

items:(1)
  - kind: "folder"
    name: project-${team_group}
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - ldap-project-${team_group}
        roles:
          - name: "developer"
    items:
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
    properties:
      - envVars:
          vars:
            FOO: "BAR"
            BAR: "BAZ"
      - folderLibraries:
          libraries:
            - libraryConfiguration:
                implicit: false
                allowVersionOverride: true
                retriever:
                  modernSCM:
                    scm:
                      github:
                        traits:
                          - gitHubBranchDiscovery:
                              strategyId: 1
                          - gitHubPullRequestDiscovery:
                              strategyId: 1
                          - gitHubForkDiscovery:
                              trust:
                                gitHubTrustEveryone: {}
                              strategyId: 1
                        repoOwner: "company"
                        id: "library-id"
                        repository: "project-alpha"
                        configuredByUrl: true
                        repositoryUrl: "https://github.com/company/project-alpha"
                name: "my-library"
                includeInChangesets: true
      - folderCredentialsProperty:
          folderCredentials:
            - credentials:
                - usernamePassword:
                    password: ${secret_location}
                    scope: GLOBAL
                    description: description
                    id: test-id
                    usernameSecret: false
                    username: test-user
              domain: {}
      - itemRestrictions:
          allowedTypes:
            - "org.jenkinsci.plugins.workflow.job.WorkflowJob"
            - "hudson.matrix.MatrixProject"
            - "hudson.model.FreeStyleProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.jobTemplate.JobTemplate"
            - "com.cloudbees.hudson.plugins.folder.Folder"
            - "com.cloudbees.hudson.plugins.modeling.impl.builder.BuilderTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.auxiliary.AuxModel"
            - "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.publisher.PublisherTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.folder.FolderTemplate"
            - "com.infradna.hudson.plugins.backup.BackupProject"
          filter: true
    items:
      - kind: "freeStyle"
        name: "project-alpha-freestyle"
        displayName: "Freestyle job in the Project Alpha folder"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles:(2)
      - "developer"
      - "browser"▼

1	Items can be nested within other items, enabling users to create a folder structure.
2	Roles can be filtered, for example to allow only administrators to view certain projects.

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

items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
    scm:
      gitSCM:
        extensions:
          - checkoutOption:
              timeout: 4
        gitTool: git
        userRemoteConfigs:
          - userRemoteConfig:
              name: "developer-a"
              credentialsId: "credentials-id"
              url: "git@github.com:company/project-alpha.git"
        browser:
          githubWeb:
            repoUrl: "https://github.com/company/project-alpha"
        doGenerateSubmoduleConfigurations: false
        branches:
          - branchSpec:
              name: "*/main"
    buildDiscarder:
      logRotator:
        artifactDaysToKeep: 3
        daysToKeep: 1
        numToKeep: 2
        artifactNumToKeep: 4
    scmCheckoutStrategy:
      standard: { }
    builders:
      - shell:
          command: "pwd"▼

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

items:
  - kind: "pipeline"
    name: "project-beta-pipeline-job"
    displayName: "Project Beta Pipeline job"
    description: "This is Project Beta's Pipeline job!"
    definition:
      cpsScmFlowDefinition:
        scriptPath: "Jenkinsfile"
        scm:
          gitSCM:
            gitTool: "git"
            userRemoteConfigs:
              - userRemoteConfig:
                  name: "developer-b"
                  credentialsId: "credentials-id"
                  url: "git@github.com:company/project-beta.git"
            extensions:
              - checkoutOption:
                  timeout: 2
              - cloneOption:
                  reference: "/workspace/git"
                  noTags: false
                  honorRefspec: false
                  shallow: true
                  timeout: 5
            branches:
              - branchSpec:
                  name: "*/main"▼

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

items:
  - kind: "multibranch"
      name: "project-beta-multibranch-pipeline"
      displayName: "Project Beta Multibranch Pipeline"
      description: "This is Project Beta's Multibranch Pipeline job!"
      orphanedItemStrategy:
        defaultOrphanedItemStrategy:
          pruneDeadBranches: true
          daysToKeep: 3
          numToKeep: 4
      projectFactory:
        workflowBranchProjectFactory:
          scriptPath: "Jenkinsfile"
    sourcesList:
      - branchSource:
          source:
            github:
              traits:
                - gitHubBranchDiscovery:
                    strategyId: 1
                - gitHubPullRequestDiscovery:
                    strategyId: 1
                - gitHubForkDiscovery:
                    trust:
                      gitHubTrustEveryone: {}
                    strategyId: 1
                - headWildcardFilter:
                    excludes: "feature/*"
                    includes: "*"
                - gitHubSshCheckout:
                    credentialsId: "github-ssh"
              repoOwner: "company"
              id: "scm-source-id"
              repository: "project-alpha"
              configuredByUrl: true
              repositoryUrl: "https://github.com/company/project-beta"
          strategy:
            allBranchesSame: {}▼

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

items:
  - kind: "organizationFolder"
    name: "project-alpha-github-org"
    displayName: "Project Alpha GitHub Organization job"
    description: "This is Project Alpha's Github Organization job!"
    navigators:
      - github:
          traits:
            - checkoutOptionTrait:
                extension:
                  checkoutOption:
                    timeout: 5
            - cloneOptionTrait:
                extension:
                  cloneOption:
                    reference: main
                    noTags: false
                    honorRefspec: false
                    shallow: true
                    timeout: 6
          repoOwner: "company"
    projectFactories:
      - customMultiBranchProjectFactory:
          factory:
            customBranchProjectFactory:
              marker: ".my-marker-file"
              definition:
                cpsScmFlowDefinition:
                  scriptPath: "pipelines/default/Jenkinsfile"
                  scm:
                    gitSCM:
                      extensions:
                        - checkoutOption:
                            timeout: 4
                      gitTool: "git"
                      userRemoteConfigs:
                        - userRemoteConfig:
                            name: "admin-a"
                            credentialsId: "credentials-id"
                            url: "git@github.com:company/project-alpha.git"
                      browser:
                        githubWeb:
                          repoUrl: "git@github.com:company/project-alpha"
                      branches:
                        - branchSpec:
                            name: "*/main"
                  lightweight: false▼

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

items:
  - kind: "organizationFolder"
    name: "project-beta-bitbucket-org"
    displayName: "Project Beta Bitbucket Organization job"
    description: "This is Project Beta's Bitbucket Organization job!"
    navigators:
      - bitbucket:
          traits:
            - bitbucketBranchDiscovery:
                strategyId: 1
            - bitbucketPullRequestDiscovery:
                strategyId: 1
            - bitbucketForkDiscovery:
                trust:
                  bitbucketTrustTeam: {}
                strategyId: 1
          repoOwner: "company"
    projectFactories:
      - workflowMultiBranchProjectFactory:
          scriptPath: "Jenkinsfile"▼

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

items:
  - kind: "cloudbeesTemplatedJob"
    name: "job-template-alpha"
    model: "folder1/template"(1)
    attributes:(2)
      - value: job-template-alpha(3)
        key: name
      - value: the description
        key: description
      - value: pwd
        key: command▼

1	The full path to the template.
2	Attributes defined in the CloudBees job template.
3	The name of the new instance you are creating based on the template.

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

items:
  - kind: "cloudbeesTemplatedJob"
    name: "my-new-job"
    catalog: "project-alpha-pipeline-template-catalog"(1)
    model: "template-alpha"(2)
    attributes:(3)
      - value: template-alpha(4)
        key: name
      - value: the description
        key: description
      - value: pwd
        key: command▼

1	The name of the Pipeline Template Catalog that is defined in the `catalog.yaml` file.
2	The name of the template within the Pipeline Template Catalog.
3	Attributes defined in the CloudBees job template.
4	The name of the new job you are creating based on the template.

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

items:
  - kind: backupAndRestore
    name: project-alpha-backup
    displayName: "Project Alpha backup"
    description: "This is Project Alpha's backup job!"
    buildersList:
      - backupBuilder:
          subjects:
            - buildRecordSubject:
                excludes: foo
            - jobConfigurationSubject:
                excludes: bar
            - systemConfigurationSubject:
                excludes: baz
                omitMasterKey: true
          format:
            zipFormat: {}
          exclusive: false
          store:
            s3Store:
              bucketName: bucket
              sse: true
              bucketFolder: bucketFolder
              credentialsId: testCredential
              region: us-east-1
          retentionPolicy:
            exponentialDecayRetentionPolicy: {}
          safeDelaySeconds: 42
    label: agent-for-backup
    triggers:
      - cron:
          spec: 0 0 * * *
    buildDiscarder:
      logRotator:
        numToKeep: 5▼

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

items:
  - kind: backupAndRestore
    name: project-alpha-restore
    displayName: "Project Alpha restore"
    description: "This is Project Alpha's restore job!"
    buildersList:
      - restoreBuilder:
          ignoreConfirmationFile: false
          preserveJenkinsHome: true
          ignoreDigestCheck: true
          store:
            s3Store:
              bucketName: bucket
              sse: true
              bucketFolder: bucketFolder
              credentialsId: testCredential
              region: us-east-1
          restoreDirectory: /tmp
    label: agent-for-restore
    buildDiscarder:
      logRotator:
        numToKeep: 5▼

rbac.yaml

The rbac.yaml file contains all files used to configure Role-Based Access Control (RBAC) within an instance. This file defines groups and roles at the root level. For more information, refer to Configuring RBAC with CasC for controllers.

Only roles and groups can be managed and only a subset of fields are supported.
Roles and groups present on the instance in the UI but not included in the items.yaml file will be removed.

The rbac.yaml file is only available on instances using CloudBees CI version 2.249.3.1 or later.

Property Type Description

removeStrategy

object

Optional. It specifies the strategy to be followed when you apply a new configuration to an existing instance.

The removeStrategy property is optional for the rbac.yaml file. However, this property is required if the rbacRemoveStrategy property is not set in the bundle.yaml file.

Valid values for this property are:

rbac:
- sync: If the role or group already exists but the configuration changes, the new configuration is applied and the existing groups or roles are deleted.
- update: If the role or group already exists but the configuration changes, only the existing role or group is updated and replaced with the new role or group.

The removeStrategy property is declared in the bundle descriptor in the bundle.yaml file. If a removeStrategy property is not declared, the default option none is used. When a removeStategy is declared in the parent bundle but not the child bundle, the effective bundle uses the removeStrategy of the parent. If the child bundle also declares a removeStategy property in the bundle descriptor, the effective bundle uses the removeStategy of the child bundle.
If removeStrategy is declared for the rbac.yaml file, the rbac property values must be defined.

rbac

string

Required. Specifies how an existing configuration is handled when a new configuration is applied.

sync: If the role or group already exists but the configuration changes, the new configuration is applied and the existing groups or roles are deleted.
update: If the role or group already exists but the configuration changes, only the existing role or group is updated and replaced with the new role or group.

groups

list of objects

Required. The list of RBAC groups available on the controller.

name

string

Required. The name of the RBAC group.

members

list of lists

Required. The list of users included as members of the RBAC group. There are several types of members including: users, internal_groups, and external_groups.

users

list of strings

Optional. The list of user ids of users who belong to the RBAC group.

internal_groups

list of strings

Optional. The list of groups created in the CloudBees CI instance that belong to the RBAC group.

external_groups

list of strings

Optional. The list of groups imported from an identity provider (such as LDAP) that belong to the RBAC group.

roles

list of objects

Required. The list of RBAC roles that are assigned to this RBAC group.

name

string

Required. The name of the RBAC role assigned to the RBAC group.

grantedAt

string

Optional. The level the RBAC role is applicable. Available values include: current, child, or grandchild. The default level is current.

propagates

boolean

Optional. The setting for if the role propagates. The default value is true.

roles

list of objects

Required. The list of RBAC roles available on the controller.

name

string

Required. The name of the RBAC role.

filterable

boolean

Optional. The setting for if the role is filterable. The default value is true.

permissions

list of strings

Optional. The list of permissions authorized for members assigned this RBAC role. Can be empty if a member has no permissions assigned.

Example rbac.yaml file

removeStrategy:
  rbac: "SYNC"(1)

roles:
  - name: administer
    permissions:
      - hudson.model.Hudson.Administer
  - name: developer
    permissions:
      - hudson.model.Hudson.Read
      - hudson.model.Item.Read
      - hudson.model.Item.Create
      - hudson.model.Item.Configure
    filterable: "true"(2)
  - name: browser
    permissions:
    - hudson.model.Hudson.Read
    - hudson.model.Item.Read
    filterable: "true"
  - name: authenticated
    filterable: "true"
    permissions:
    - hudson.model.Hudson.Read

groups:
  - name: Administrators
    roles:
      - name: administer
        grantedAt: current(3)
    members:
      users:
        - admin
      external_groups:
        - ${external_admin_group}
  - name: Developers
    roles:(4) (5)
      - name: developer
    members:
      users:
        - developer
      internal_groups:
        - "some-other-group"
      external_groups:
        - "ldap-cb-developers"
  - name: Browsers
    roles:
      - name: browser
    members:
      users:
        - read▼

1	For security reasons, SYNC is here to remove groups/roles from CloudBees Continuous Integration when they are removed from this file.
2	If filterable is not included, the default value is “false”.
3	Other options that could be used here include: "child" or "grandchild".
4	If propagates is not included, the default value is "true".
5	If grantedAt is not included, the default value is "current".

variables.yaml

The variables.yaml file defines the variables that can be used in the jenkins.yaml, items.yaml, and rbac.yaml files with the placeholder ${}, for example ${team_name}. Variables are not supported for the plugins.yaml and plugin-catalog.yaml files.

To escape a string from variable substitution, the literal ^ must be placed in front of the expression. For example, ^${variableName} resolves to ${variableName}. For more information, refer to Passing secrets through variables.

Example variables.yaml file

  variables:
    - key: value
    - long_text: |-
        multiline string without
        quotes
    - another: text
    - team_name: Team Alpha
    - team_group: alpha
    - external_admin_group: ldap-cb-admins▼

Exporting a CasC configuration

You can export a CasC configuration from an existing controller to create a template bundle. You can use the template bundle to set up a new controller and connect it to the operations center with Configuration as Code. However, the exported configuration should only be used as a starting point and must be manually updated.

You can also export an individual CasC item and use it to create a new item by adding it to the items.yaml file. For more information, refer to Exporting an individual CasC item.

The export feature in Configuration as Code relies on Jenkins LTS - Configuration as Code export, which has limitations. Therefore, the exported configuration is not a complete, correct, and ready-to-use CasC bundle. For more information, refer to the JCasC Jenkins LTS documentation.
The exported configuration is incomplete because some plugins are only partially compatible with Configuration as Code. They can read and load the CasC configuration, however, they do not generate the correct YAML files when exporting. In addition, the jenkins.yaml file may include extraneous default values for some properties that can be removed.
When exporting CasC bundles from existing controllers, you must verify the controller has no BeeKeeper plugin warnings, as the export logic relies on the CAP to generate consistent plugins.yaml and plugin-catalog.yaml files. If there are BeeKeeper warnings, the export still returns content, but the consistency of the plugins.yaml and plugin-catalog.yaml files cannot be guaranteed. The files may be unusable and require modifications due to warning comments in the files for plugin conflicts.

To prevent the environment configuration from being leaked, the variable expressions within exports are escaped. In the following pipeline example:

pipeline {
  agent any

  environment {
    greeting = 'Hello, World!'
  }

  stages {
    stage('Print Greeting') {
      steps {
        echo "${env.greeting}"
        sh 'echo ${GLOBAL_ENV}'
      }
    }
  }
}▼

The export renders as follows:

kind: pipeline
name: testWithVars
concurrentBuild: true
definition:
  cpsFlowDefinition:
    sandbox: true
    script: |-
      pipeline {
        agent any

        environment {
          greeting = 'Hello, World!'
        }

        stages {
          stage('Print Greeting') {
            steps {
              echo "^${env.greeting}" (1)
              sh 'echo ^${GLOBAL_ENV}'
            }
          }
        }
      }
description: ''
disabled: false
displayName: testWithVars1
resumeBlocked: false▼

1	The user must remove the ^ characters where it applies.

Prerequisites

The following software and plugins must be installed to export the current configuration:

If using CloudBees CI 2.249.3.1 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.2 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Client plugin, version 1.44 or later
Configuration as Code plugin

Exporting the current configuration

To export the current configuration from an existing controller:

Create a test controller in your cluster using the UI.
Configure the controller’s plugins and global configuration using the UI.
Optionally, configure a plugin catalog using the UI.
From the controller, select Manage Jenkins in the left pane.
Select CloudBees Configuration as Code export and update.

Figure 2. CloudBees Configuration as Code export and update
Select Current configuration.

Figure 3. Current configuration

Select Download to export the configuration. You can export individual YAML files or export all files in zip format.

You can have a configuration bundle without the plugins.yaml, plugin-catalog.yaml, rbac.yaml, and items.yaml files. If you do not include these files in your bundle, do not list them in your bundle.yaml file.

If CAP/Beekeeper is disabled on the controller, the exported configuration includes the plugins.yaml and plugin-catalog.yaml files, but they contain one of the following warning messages:

plugin-catalog.yaml message: Cannot export catalog because CAP is not enabled
plugins.yaml message: Cannot export plugins because CAP is not enabled

Save the files using the following file names:
- bundle.yaml
- jenkins.yaml
- plugins.yaml
- plugin-catalog.yaml
- rbac.yaml
- items.yaml
- variables.yaml
  
  For the bundle to be valid, the above files must use these exact filenames.

After creating a bundle based on the exported configuration, add the bundle to the operations center, configure the bundle availability, and set up a new controller. For more information, refer to:

Configuring bundle availability for controllers
Setting up a managed controller using CasC

Setting up a client controller using CasC

You must remove the obsolete operationsCenterRootAction connection details from the jenkins.yaml file before connecting it to the operations center so new connection details can be established for the new controller. Connection details are controller-specific, and cannot be shared between controllers. If you release a client controller, the connection details also change. Do not include them unless you know what you are doing. If operationsCenterRootAction is not present in the jenkins.yaml file, the operations center creates it in the background.

Remove the license: section from the jenkins.yaml file if the controller is connected to an operations center, so the operations center can automatically update the license.

Delete the original test controller created in the UI; it is no longer needed.

If the controller has not been configured a CasC bundle, the exported bundle uses apiVersion:1 in the bundle.yaml file. However, if a CasC bundle has been used to configure the controller, when exporting the current configuration, the value for the apiVersion property in the bundle.yaml is the value for the calculated effective bundle.

Review how inheritance can affect this apiVersion value in the effective bundle here.

Using YAML anchors

If a YAML file contains repetitive elements, you can replace them with YAML anchors. Any part of the YAML file can be defined as an anchor and used as the reference if the anchor name has a prefix of x-.

Example of YAML anchors

The following example items.yaml file has the x-colors-declaration anchor that is used in the choice parameter element.

  x-colors-declaration: &colors
  - red
  - green
  - blue

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

  items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
    blockBuildWhenDownstreamBuilding: false
    blockBuildWhenUpstreamBuilding: false
    concurrentBuild: false
    parameters:
    - choice:
        name: foreground-color
        choices: *colors
    - choice:
        name: background-color
        choices: *colors
    scm:
      none: {}
    scmCheckoutStrategy:
      standard: {}▼

This produces the following result:

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

  items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
    blockBuildWhenDownstreamBuilding: false
    blockBuildWhenUpstreamBuilding: false
    concurrentBuild: false
    parameters:
    - choice:
        name: foreground-color
        choices:
        - red
        - green
        - blue
    - choice:
        name: background-color
        choices:
        - red
        - green
        - blue
    scm:
      none: {}
    scmCheckoutStrategy:
      standard: {}▼

Composing CasC bundles

There are several options for composing CasC bundles. You can compose:

A single bundle
A single bundle with folders and subfolders
Multiple bundles
Multiple bundles with bundle inheritance

Single bundle

A single CasC bundle is composed of individual YAML files stored in a folder and the bundle is deployed to the operations center.

For more information, refer to Adding controller CasC bundles to the operations center.

Example single bundle

/oc-bundles
└── bundle-1
    ├── bundle.yaml
    ├── jenkins.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    ├── rbac.yaml
    └── variables.yaml▼

Single bundle with folders and subfolders

Configuration settings can be stored in individual YAML files, and the files stored within folders and subfolders in the bundle.

CloudBees recommends that each YAML file contain only unique configuration elements that do not override configuration elements in other YAML files.

The Plugin Catalog does not support storing configuration settings in individual YAML files.

Avoiding YAML file overrides

An override in a YAML file does not include the whole file but properties within the YAML file. For example, if items1.yaml defines a property and items2.yaml defines the same property then:

Properties not defined in items2.yaml will have the same value as properties from items1.yaml.
Properties defined in items2.yaml will override the value of properties from items1.yaml.

The override behavior is the same for rbac.yaml files.
For the variables.yaml files, the override occurs on the unique value of the variable so that the last value prevails.

To prevent undesired item overrides, YAML files are read as follows:

If files are listed in the section, they are read in that order, so the last file overrides the first.
If the folder containing the files is referenced instead of listing them, the files are read in alphanumeric order.
If there is inheritance, child files override their parent files.

Example bundle with folders

In this example, a configurations folder contains individual YAML files:

/oc-bundles
└── bundle-1
    ├── bundle.yaml
    ├── configurations
    │    ├── jenkins.yaml
    │    └── security.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    ├── rbac.yaml
    └── variables.yaml▼

The bundle.yaml file lists each individual YAML file:

id: "bundle-1"
version: "1"
apiVersion: "1"
description: "My CloudBees Configuration as Code (CasC) bundle"
jcasc:
  - "configurations/jenkins.yaml"
  - "configurations/security.yaml"
plugins:
  - "plugins.yaml"
catalog:
  - "plugin-catalog.yaml"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"
variables:
  - "variables.yaml"▼

Example bundle with subfolders

In this example, the configurations folder contains a jenkins subfolder, and the jenkins subfolder contains the individual YAML files:

/oc-bundles
└── bundle-1
    ├── bundle.yaml
    ├── configurations
    │    └── jenkins
    │         └── jenkins.yaml
    │         └── security.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    ├── rbac.yaml
    └── variables.yaml▼

This allows you to add or remove YAML files from the subfolder without requiring that you update the bundle.yaml file:

id: "bundle-1"
version: "1"
apiVersion: "1"
description: "My CloudBees Configuration as Code (CasC) bundle"
jcasc:
  - "configurations/jenkins/"
plugins:
  - "plugins.yaml"
catalog:
  - "plugin-catalog.yaml"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"
variables:
  - "variables.yaml"▼

Multiple bundles

Multiple bundles can also be deployed to the operations center.

For more information, refer to Adding controller CasC bundles to the operations center.

Example folders for multiple bundles

/oc-bundles
├── bundle-1
│   ├── bundle.yaml
│   ├── jenkins.yaml
│   ├── plugins.yaml
│   ├── plugin-catalog.yaml
│   ├── items.yaml
│   ├── rbac.yaml
│   └── variables.yaml
└── bundle-2
    ├── bundle.yaml
    ├── jenkins.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    ├── rbac.yaml
    └── variables.yaml▼

Multiple bundles with bundle inheritance

"Child" bundles can also be configured to inherit from a "parent" bundle.

For more information, refer to Configuring bundle inheritance with CasC.

Example folder structure for 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▼

In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.

Creating a CasC bundle for controllers

Manually creating a configuration bundle

bundle.yaml

Example bundle.yaml file

jenkins.yaml

Example jenkins.yaml file

plugins.yaml

plugin-catalog.yaml

Example plugin-catalog.yaml file

items.yaml

Configure the items.yaml file to handle variable expressions

Example items.yaml file

rbac.yaml

Example rbac.yaml file

variables.yaml

Example variables.yaml file

Exporting a CasC configuration

Prerequisites

Exporting the current configuration

Using YAML anchors

Example of YAML anchors

Composing CasC bundles

Single bundle

Example single bundle

Single bundle with folders and subfolders

Avoiding YAML file overrides

Example bundle with folders

Example bundle with subfolders

Multiple bundles

Example folders for multiple bundles

Multiple bundles with bundle inheritance

Example folder structure for bundle inheritance

Configure the `items.yaml` file to handle variable expressions