Creating a CasC bundle for the operations center

The configuration of the operations center is described in a collection of YAML files referred to as a CasC bundle.

CloudBees does not recommend adding your CloudBees CI license or certificate to the CasC bundle for the operations center because these values are hardcoded. If you do add a license key or certificate to your CasC bundle, you must manually ensure they are always up-to-date, because they will be the only license and certificate the operations center can read.

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.
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.

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.

bundle.yaml

The bundle.yaml file is an index file that describes the bundle and references the other files in the bundle.

Property Type Description

Property	Type	Description
id	string	Required. This bundle’s unique identifier. NOTE: 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. 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.
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.
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.

string

Required. This bundle’s unique identifier. NOTE: 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. 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.

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.

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"
jcasc:
  - "jenkins.yaml"
jcascMergeStrategy: "errorOnConflict"
plugins:
  - "plugins.yaml"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"
variables:
  - "variables.yaml"

jenkins.yaml

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

Example jenkins.yaml file

jenkins:
  systemMessage: "Operations center 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)
security:
  securitySettingsEnforcement:
    global:
      realmAndAuthorization:
        canCustomMapping: false
        canOverride: true
        defaultMappingFactory: "restrictedEquivalentRAMF"
  controllerExecutorCount:
    enforce:
      canOverride: false
      count: 0
cloudBeesCasCServer:
  visibility: true (2)
unclassified:
  cascAutoControllerProvisioning:
    provisionControllerOnCreation: true (3)
    fireAndForget: true (4)
    initialDelay: 15  (5)
    timeout: 600 (6)
    duration: 60 (7)
  location:
    url: https://operations-center:8888/ (8)
  bundleStorageService: (9)
    activated: true
    activeBundle:
      name: "local-folder"
      retriever:
        SCM:
          scmSource:
            git:
              id: "acf88621-05a0-4d50-9166-d7767868dc43"
              remote: "https://github.com/my-company/repo.git"
              traits:
              - "gitBranchDiscovery"
    pollingPeriod: 0
    purgeOnDeactivation: false

1	Required to use CloudBees RBAC configured using CasC.
2	Optional if using the `items.yaml` file to create a controller item. When `visibility` is set to `true`, all CasC bundles that do not have an availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.
3	When `provisionControllerOnCreation` is set to `true`, all managed controller items are provisioned automatically after they are created using CasC.
4	When `fireAndForget` is set to `true`, the automatic provisioning process starts immediately, and does not wait for the controller to be connected.
5	The amount of time, in seconds, to wait before starting the automatic provisioning process.
6	The amount of time, in seconds, to complete the automatic provisioning process. If `fireAndForget` is set to `false`, this timeout may prevent queued provisioning requests from being blocked.
7	The provisioning duration, in seconds. After the initial delay, controllers are provisioned at random in batches of 20 controllers, for this time period. Increase this value to increase the amount of time between controller provisioning requests. If provisioning more than 20 controllers, the provisioning process will exceed the specified duration.
8	Required to create client controller items. The `url` is the operations center URL.
9	Required if using a local folder on the operations center server or an SCM tool as the Configuration as Code bundle location.

plugins.yaml

This file lists all plugins to be installed on the controller or the operations center. The plugins listed in this file must be included in the CloudBees Assurance Program (CAP) as Tier 1 or Tier 2 plugins. Plugins not included in CAP are installed via the 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 CAP
  - id: "cloudbees-casc-client"
  - id: "cloudbees-casc-items-api"
  - id: "cloudbees-casc-items-commons"
  - id: "cloudbees-casc-items-server"
  - id: "configuration-as-code"
  - id: "operations-center-rbac"

items.yaml

The items.yaml file contains a list of items to create or update within the instance. For more information, refer to Creating items with CasC for the operations center.

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.
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.

Property Type Description

Property	Type	Description
removeStrategy	object	Required. It specifies the strategy to be followed when applying 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 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 restarts item creation. NOTE: 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 will use the `removeStrategy` of the parent. If both the parent and the child bundle declares a `removeStrategy` then the parent bundle will use the `removeStrategy` of the child bundle.
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.
items	list of objects	Required. The list of items.
kind	string	Required. It defines the kind of item created. Supported items: backupAndRestore clientController clusterOpProject folder freeStyle managedController sharedAgent sharedCloud
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.

removeStrategy

object

Required. It specifies the strategy to be followed when applying 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 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 restarts item creation.

NOTE: 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 will use the removeStrategy of the parent. If both the parent and the child bundle declares a removeStrategy then the parent bundle will use the removeStrategy of the child bundle.

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.

items

list of objects

Required. The list of items.

kind

string

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

backupAndRestore
clientController
clusterOpProject
folder
freeStyle
managedController
sharedAgent
sharedCloud

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 creating a new controller item, refer to Creating a new controller item using CasC for the operations center.
By default, shared agent and shared cloud agent items are configured to be taken online. To configure the shared agent or shared cloud agent item to be taken offline, add the takeOnline property to the items.yaml and set it to false. For example: takeOnline: false.

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: clusterOpProject
    name: "project-alpha-cluster-operations"
    displayName: "Project Alpha - Cluster operations"
    description: "These are Project Alpha's cluster operations!"
	disabled: false
    concurrentBuild: true
	operations:
      - masterClusterOperation:
          failureMode: IMMEDIATELY
          clusterOpSteps:
            - backupClusterOpStep:
                subjects:
                  - buildRecordSubject: {}
                  - jobConfigurationSubject: {}
                format:
                  zipFormat: {}
                retentionPolicy:
                  exponentialDecayRetentionPolicy: {}
                safeDelaySeconds: 10
                store:
                    s3Store:
                        bucketName: ' mybucket'
                        sse: true
                        bucketFolder: somefolder
                        credentialsId: 'my-aws-credentials-id'
                        region: us-east-1
          timeoutSeconds: 0
          itemSource:
              jenkinsRootItemSource: {}
          filters:
            - isMasterOnlineFilter: {}
          inParallel: 0
          noRetries: 0

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

items:
  - kind: managedController
    displayName: "managed-controller-alpha"
    name: "managed-controller-alpha"
    description: "This is Project Alpha's managed controller!"
    groups:
      - name: "Project Alpha Developers"
        members:
          users:
            - developer-1
        roles:
          - name: developer
    properties:
      - configurationAsCode:
          bundle: bundle-1
      - healthReporting:
          enabled: false
      - owner:
          delay: 5
          owners: ''
      - envelopeExtension:
          allowExceptions: false
      - sharedConfigurationOptOut:
          optOut: false
      - licensing:
          strategy:
            perUserLicensingStrategy: {}
    configuration:
      kubernetes:
        allowExternalAgents: false
        terminationGracePeriodSeconds: 1200
        #image: cloudbees/mc-foo-image # uncomment to use a non-default image
        memory: 3072 (1)
        fsGroup: '1000'
        cpus: 1.0
        readinessTimeoutSeconds: 5
        livenessInitialDelaySeconds: 300
        readinessInitialDelaySeconds: 30
        clusterEndpointId: default
        disk: 50
        readinessFailureThreshold: 100
        livenessTimeoutSeconds: 10
        domain: managed-controller-alpha
        livenessPeriodSeconds: 10
        javaOptions: -DfooSystemProperty="foo" -Dbar="bar"
        yaml: |-
          ---
          apiVersion: apps/v1
          kind: StatefulSet
          metadata:
            labels:
              my-label: my-value

1	Some settings, such as controller memory, require the controller to be re-provisioned for the setting to take effect.

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

items:
  - kind: clientController
    displayName: "client-controller-beta"
    name: "client-controller-beta"
    description: "This is Project Beta's client controller!"
    groups:
      - name: "Project Beta Developers"
        members:
          users:
            - developer-1
        roles:
          - name: developer
    properties:
    - configurationAsCode:
        bundle: bundle-2
    - healthReporting:
        enabled: false
    - owner:
        delay: 5
        owners: ''
    - envelopeExtension:
          allowExceptions: false
    - sharedConfigurationOptOut:
          optOut: false
    - licensing:
        strategy:
          perUserLicensingStrategy: {}
    - webSocket:
        enabled: true

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

items:
  - kind: "sharedAgent"
    displayName: "Shared Agent for this cluster"
    name: "shared-agent-1"
    description: "Shared Agent for this cluster"
    remoteFS: "/tmp/remote"
    properties:
      - sharedAgent:
          customizers:
            - envVars:
                value:
                  SKIP_RELEASE: "TRUE"
                  JENKINS_VERSION: "2.303"
            - toolLocation:
                value:
                  - name: "git"
                    type: "git"
                    home: "/usr/local/git"
                  - name: "maven3"
                    type: "mvn"
                    home: "/usr/local/mvn"
    labels: "ubuntu"
    launcher:
      inboundAgent:
        webSocket: true
        workDirSettings:
          remotingWorkDirSettings:
            internalDir: "/path/to/directory"
            disabled: false
            failIfWorkDirIsMissing: true
            workDirPath: "/path/to/directory"
        agentStartupOptions: "-noCertificateCheck"
        vmargs: "-Xms2G -Xmx2G"
        tunnel: "192.1.1.45:22"
    mode: EXCLUSIVE
    numExecutors: 10
    retentionStrategy:
      sharedNodeRetentionStrategy: {}

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

items:
  - kind: "sharedCloud"
    displayName: "Shared Cloud Agent for this cluster"
    name: "shared-cloud-1"
    description: "Shared Cloud Agent for this cluster"
    properties:
      - sharedCloud:
          customizers:
            - envVars:
                value:
                  SKIP_RELEASE: "TRUE"
                  JENKINS_VERSION: "2.303"
            - toolLocation:
                value:
                  - name: "git"
                    type: "git"
                    home: "/usr/local/git"
                  - name: "maven3"
                    type: "mvn"
                    home: "/usr/local/mvn"
    cloud:
      inboundAgents:
        mode: EXCLUSIVE
        numExecutors: 10
        remoteFS: "/path/to/directory"
        labels: "ubuntu"
        launcher:
          inboundAgent:
            webSocket: true
            workDirSettings:
              remotingWorkDirSettings:
                internalDir: "/path/to/directory"
                disabled: false
                failIfWorkDirIsMissing: true
                workDirPath: "/path/to/directory"
            agentStartupOptions: "-noCertificateCheck"
            vmargs: "-Xms2G -Xmx2G"
            tunnel: "192.1.1.45:22"

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

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 the operations center.

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.

Property Type Description

Property	Type	Description
removeStrategy	object	Required. It specifies the strategy to be followed when applying 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 exiting items with the values from the YAML file. Items not declared in the `items.yaml` file remain as is on the controller. * sync: Deletes CasC supported items not defined in the `rbac.yaml` file. Items in the `rbac.yaml` will continue in the same way as the none 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. NOTE: 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 will use that of the parent. If both the parent and the child bundle declares a `removeStrategy` then the parent bundle will use the `removeStrategy` of the child bundle.
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.

removeStrategy

object

Required. It specifies the strategy to be followed when applying 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 exiting items with the values from the YAML file. Items not declared in the items.yaml file remain as is on the controller.

* sync: Deletes CasC supported items not defined in the rbac.yaml file. Items in the rbac.yaml will continue in the same way as the none 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.

NOTE: 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 will use that of the parent. If both the parent and the child bundle declares a removeStrategy then the parent bundle will use the removeStrategy of the child bundle.

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. Variables are not supported for the plugins.yaml file.

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 operations center instance to create a template bundle. You can use the template bundle to set up a new operations center instance using CasC. However, the exported configuration should not be used as is 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 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 operations center instances, you must verify there are no BeeKeeper plugin warnings, as the export logic relies on the CloudBees Assurance Program (CAP) to generate a consistent plugins.yaml file. If there are BeeKeeper warnings, the export still returns content, but the consistency of the plugins.yaml file cannot be guaranteed. The files may be unusable and require modifications due to warning comments in the files for plugin conflicts.

Prerequisites

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

If using CloudBees CI 2.289.3.2 - 2.303.3.3: CloudBees CasC API Plugin (Deprecated), version 1.14 - 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 a test operations center instance:

Install operations center as a test instance.
Configure the plugins and global configuration using the UI.
Select Manage Jenkins in the left pane.
Select CloudBees Configuration as Code export and update.

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

Figure 2. 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, items.yaml, and rbac.yaml files. If you do not include these files in your bundle, do not list them in your bundle.yaml file.
Save the files using the following file names:
- bundle.yaml
- jenkins.yaml
- plugins.yaml
- items.yaml
- rbac.yaml
- variables.yaml
  
  For the bundle to be valid, the above files must use these exact filenames. If you rename these files, you must update them in your bundle.yaml file.
Uninstall the original operations center test instance; it is no longer needed.

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: {}