Create CasC bundles

5 minute read

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

jenkins.yaml

Required

Required

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

items.yaml

Optional

Optional

rbac.yaml

Optional

Optional

variables.yaml

Optional

Optional

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