# Create CasC bundles

Create CasC bundles
===================

[Get started with CasC](/docs/cloudbees-ci/latest/casc-commons/casc-intro) 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](/docs/cloudbees-ci/latest/casc-bundle-reference/bundle-yaml)

`jenkins.yaml`

Required

Required

[jenkins.yaml file reference](/docs/cloudbees-ci/latest/casc-bundle-reference/jenkins-yaml)

`plugins.yaml`

Optional

Optional

[plugins.yaml file reference](/docs/cloudbees-ci/latest/casc-bundle-reference/plugins-yaml). Refer to [Manage plugins with CasC](/docs/cloudbees-ci/latest/casc-plugin-management/) for more information on managing plugins with CasC.

`plugin-catalog.yaml`

N/A

Optional

[plugin-catalog.yaml file reference](/docs/cloudbees-ci/latest/casc-bundle-reference/plugin-catalog-yaml)

`items.yaml`

Optional

Optional

[items.yaml file reference](/docs/cloudbees-ci/latest/casc-bundle-reference/items-yaml)

`rbac.yaml`

Optional

Optional

[rbac.yaml file reference](/docs/cloudbees-ci/latest/casc-bundle-reference/rbac-yaml)

`variables.yaml`

Optional

Optional

[variables.yaml file reference](/docs/cloudbees-ci/latest/casc-bundle-reference/variables-yaml)

[](#_create_a_casc_bundle)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](/docs/cloudbees-ci/latest/casc-bundle-reference/) for detailed information on all the files and properties.
    
*   [Exporting](/docs/cloudbees-ci/latest/casc-create-bundle/export-casc-configuration) 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)Bundle files examples
------------------------------------------------

### [](#_example_bundle_yaml_file)Example bundle.yaml file

#### [](#_bundle_yaml_for_a_controller)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)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)Example jenkins.yaml file

#### [](#_jenkins_yaml_for_a_controller)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.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)Example plugins.yaml file

#### [](#_plugins_yaml_for_a_controller)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.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)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:
          extended-read-permission:(2)
            version: "68.vd270568a_7520"(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 `extended-read-permission` plugin to enable the **Overall/SystemRead** and **Job/ExtendedRead** permission.

**3**

Replace 68.vd270568a\_7520 with the most recent version.

### [](#_example_rbac_yaml_file)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)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