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
, andrbac.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:
File | Operations center | Controller | Complete reference |
---|---|---|---|
|
Required |
Required |
|
|
Required |
Required |
|
|
Optional |
Optional |
plugins.yaml file reference. Refer to Plugin management with CasC for more information on managing plugins with CasC. |
|
N/A |
Optional |
|
|
Optional |
Optional |
|
|
Optional |
Optional |
|
|
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"
Example plugin-catalog.yaml file
The |
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". |