Creating a CasC bundle

14 minute readScalabilityAutomation

The configuration of a controller is described in a collection of YAML files referred to as a Configuration as Code (CasC) for Controllers 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 (CasC) for Controllers 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.

For the bundle to be valid, the above files must have exactly these filenames.
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.

PropertyTypeDescription

id

string

Required. This bundle’s unique identifier.

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.

apiVersion

string

Required. This is the bundle’s API version. The expected value is "1".

description

string

Optional. A helpful description of the bundle.

parent

string

Optional. The parent bundle’s unique identifier. For more information, refer to Configuring bundle inheritance with CasC.

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. For more information, refer to Configuring bundle availability for controllers.

jcasc

list of strings

Required. This indicates the bundle contains a jenkins.yaml file. This item must be included as the jenkins.yaml file is required.

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.

rbac

list of strings

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

Example bundle.yaml file

id: "bundle-1"
version: "1"
apiVersion: "1"
description: "My CloudBees Configuration as Code (CasC) bundle"
availabilityPattern: "folder1/.*"
parent: "bundle-global"
jcasc:
  - "jenkins.yaml"
plugins:
  - "plugins.yaml"
catalog:
  - "plugin-catalog.yaml"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"

jenkins.yaml

This file is the main Configuration as Code (CasC) for Controllers configuration file that describes the controller. For more information on how to format this file, see the documentation of the Jenkins Configuration-as-Code plugin.

Example jenkins.yaml file

jenkins:
  systemMessage: "Jenkins configured using 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)
1Mandatory to use CloudBees RBAC configured with CasC.

plugins.yaml

This file lists all plugins that should be installed on the controller. Plugins outside of the CloudBees Assurance Program (CAP) should be added via a Plugin Catalog. For more information, see plugin-catalog.yaml.

The contents of this file should be a list of plugin IDs. Find many popular plugins and their IDs at the following sites:

Example plugins.yaml file

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: "configuration-as-code" }
  - { id: "git" }
  - { id: "github-branch-source" }
  - { id: "infradna-backup" }
  - { id: "workflow-multibranch"}
  # Not in CAP (see plugin-catalog.yaml)
  - { id: "chucknorris" }
  - { id: "manage-permission" }

plugin-catalog.yaml

This file defines the catalog of plugins that are available for installation on the controller. The plugin catalog contains a list of plugins along with the version that should be installed. 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.

For more information on creating a list of transitive dependencies, refer to Calculating plugin dependencies.

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:
      chucknorris:
        version: 1.4
      #my-custom-plugin:
        #url: http://www.example.org/jenkins-plugins/my-custom-plugin-1.2.3.hpi
      manage-permission: (2)
        version: 1.0.1 (3)
1version (required) - must currently have the value 1, which defines the current metadata format for the plugin catalog.
2Add the manage-permission plugin to enable the Overall/Manage permission.
3Replace 1.0.1 with the most recent version.

items.yaml

The purpose of the items.yaml file is to describe the items to be created in the instance. For more information, refer to Creating items with CasC for controllers.

  • Items that are present on the instance in the UI but not included in the items.yaml file will remain.

  • You must install the prerequisite CloudBees CI software and plugins based on the item type you are creating.

PropertyTypeDescription

removeStrategy

object

Required. It specifies the strategy followed to handle an existing configuration when a new configuration is applied.

items

string

Required. The only supported value is NONE. No item is going to be removed in the instance as part of the creation process.

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.

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:

  • folder

  • freeStyle

  • pipeline

  • multibranch

  • organizationFolder

  • backupAndRestore

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.

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.
Folders with limited fields
Folders with extended fields
Freestyle job
Pipeline job
Multibranch Pipeline job
GitHub Organization
Bitbucket Team/Project
Backup
Restore
removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "folder"
    name: "project-alpha"
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - "ldap-project-alpha"
        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"
1Items can be nested within other items, enabling users to create a folder structure.
2Roles can be filtered, for example to allow only administrators to view certain projects.
removeStrategy:
  items: "none"
  rbac: "sync"

items: (1)
  - kind: "folder"
    name: "project-alpha"
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - "ldap-project-alpha"
        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
      - 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"
1Items can be nested within other items, enabling users to create a folder structure.
2Roles 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: 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 purpose of the rbac.yaml file is to describe the role-based access control (RBAC) groups and roles defined 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.

PropertyTypeDescription

removeStrategy

object

Required. It specifies the strategy followed to handle an existing configuration when a new configuration is applied.

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

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 (CasC) for Controllers. 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 (CasC) for Controllers 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 CloudBees Assurance Program (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.

Prerequisites

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

Exporting the current configuration

To export the current configuration from an existing controller:

  1. Create a test controller in your cluster using the UI.

  2. Configure the controller’s plugins and global configuration using the UI.

  3. Optionally, configure a plugin catalog using the UI.

  4. From the controller, select Manage Jenkins in the left pane.

  5. Select CloudBees Configuration as Code export and update.

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

    Figure 2. Current configuration
  7. 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

  8. Save the files using the following file names:

    • bundle.yaml

    • jenkins.yaml

    • plugins.yaml

    • plugin-catalog.yaml

    • rbac.yaml

    • items.yaml

      For the bundle to be valid, the above files must use these exact filenames.
  9. 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:

    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.
  10. Delete the original test controller created in the UI; it is no longer needed.

Composing CasC bundles

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

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 a CasC bundle for controllers to the operations center.

Example single bundle

└── bundle-1
    ├── bundle.yaml
    ├── jenkins.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    └── rbac.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.

  • Each YAML file must contain only unique configuration elements and should not overwrite configuration elements in another YAML file.

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

Example bundle with folders

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

└── bundle-1
    ├── bundle.yaml
    ├── configurations
    │    ├── jenkins.yaml
    │    └── security.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    └── rbac.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"

Example bundle with subfolders

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

└── bundle-1
    ├── bundle.yaml
    ├── configurations
    │    └── jenkins
    │         └── jenkins.yaml
    │         └── security.yaml
    ├── plugins.yaml
    ├── plugin-catalog.yaml
    ├── items.yaml
    └── rbac.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"

Multiple bundles

Multiple bundles can also be deployed to the operations center. For more information, refer to Adding a CasC bundle for controllers to the operations center.

Example folders for multiple bundles

├── bundle-1
│   ├── bundle.yaml
│   ├── jenkins.yaml
│   ├── plugins.yaml
│   └── plugin-catalog.yaml
│   ├── items.yaml
│   └── rbac.yaml
└── bundle-2
    ├── bundle.yaml
    ├── jenkins.yaml
    ├── plugins.yaml
    └── plugin-catalog.yaml
    ├── items.yaml
    └── rbac.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.

$JENKINS_HOME/jcasc-bundles-store/
├── bundle-global
│   ├── bundle.yaml
│   ├── jenkins.yaml
│   ├── plugins.yaml
│   └── items.yaml
├── bundle-1
│   ├── bundle.yaml
│   └── items.yaml
└── bundle-2
    ├── bundle.yaml
    └── items.yaml