Create CasC bundles

Get started with CasC describes what Configuration as Code (CasC) is, its main advantages and uses cases, the requirements to use it, and introduces the main elements of CasC configurations, the CasC bundles.

CasC bundles are the main elements to configure your CloudBees CI instance (operations center or controller) using Configuration as Code. A CasC bundle is a collection of YAML files that describes the configuration of a CloudBees CI instance.

These files may be part of a CasC bundle:

bundle.yaml: This index file describes the bundle and references the other files in the bundle.
jenkins.yaml: This file contains the Jenkins configuration, as defined by the Jenkins 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. It’s only part of a CasC bundle for bundles describing a controller configuration.
items.yaml: (Optional) This file contains the items to be created.
rbac.yaml: (Optional) This file contains all 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.

The table below shows these files, whether they are required or optional, and if they are used in operations center or controller configurations:

Table 1. CasC bundle files
File	Operations center	Controller	Complete reference
`bundle.yaml`	Required	Required	bundle.yaml file reference
`jenkins.yaml`	Required	Required	jenkins.yaml file reference
`plugins.yaml`	Optional	Optional	plugins.yaml file reference. Refer to Plugin management with CasC for more information on managing plugins with CasC.
`plugin-catalog.yaml`	N/A	Optional	plugin-catalog.yaml file reference
`items.yaml`	Optional	Optional	items.yaml file reference
`rbac.yaml`	Optional	Optional	rbac.yaml file reference
`variables.yaml`	Optional	Optional	variables.yaml file reference

Create a CasC bundle

CasC bundles can be created in two ways:

Manually, creating from scratch the files listed above. Refer to the CasC bundle complete reference for detailed information on all the files and properties.
Exporting from a CloudBees CI instance by means of the CloudBees Configuration as Code export and update screen in the UI, or an API HTTP request.

Once the CasC bundles have been created, either manually or by exporting the configuration for a running CloudBees CI instance, you can configure an instance using them, by either placing the bundles:

In a local folder within the instance you want to configure using the bundle.
In an SCM that will provide the bundle to configure your instance.

Bundle files examples

Example bundle.yaml file

bundle.yaml for a controller

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

bundle.yaml for an operations center

id: "bundle-1"
version: "1"
apiVersion: "2"
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"▼

Example jenkins.yaml file

jenkins.yaml for a controller

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

jenkins.yaml for an operations center

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.

Example plugins.yaml file

plugins.yaml for a controller

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

plugins.yaml for an operations center

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

Example plugin-catalog.yaml file

The plugin-catalog.yaml file is only part of a CasC bundle for bundles describing a controller configuration.

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.

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

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▼