The configuration of a controller is described in a collection of YAML files referred to as a Configuration as Code bundle. The operations center can store many different configuration bundles representing a selection of predefined controllers. Configuration bundles are stored securely on the operations center server which manages the secure distribution of the Configuration as Code bundles to the correct controllers.
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.
-
plugin-catalog.yaml: (Optional) This file contains the plugin catalog definitions that should be created on the controller.
-
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
, andrbac.yaml
files.
|
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.
|
The items.yaml and rbac.yaml files are only available in CloudBees CI release 2.249.3.1 or later.
|
bundle.yaml
The bundle.yaml
file is an index file that describes the bundle and references the other files in the bundle.
It can also be used to optionally configure bundle inheritance and bundle availability.
Property | Type | Description | ||||
---|---|---|---|---|---|---|
id |
string |
Required. This bundle’s unique identifier.
|
||||
version |
string |
Required. The bundle’s version.
If a controller is configured with a bundle using the
|
||||
apiVersion |
string |
Required. This is the bundle’s API version. Valid values are
|
||||
description |
string |
Optional. A helpful description of the bundle. |
||||
parent |
string |
Optional. The parent bundle’s unique folder name. This property provides bundle inheritance for CasC bundles that are added to the operations center using the CasC bundle location. This property is not supported if using an HTTP API endpoint or a CLI command to upload a bundle to the operations center. With branch and tag support, the value of the
For more information, refer to Configuring bundle inheritance with CasC. |
||||
allowCapExceptions |
boolean |
Optional. Allows Beekeeper plugin exceptions in the controller’s
|
||||
availabilityPattern |
string |
Optional. Specifies the regex availability pattern, to define the full path to one or more controllers in the operations center that can use the CasC bundle. This property provides bundle availability for CasC bundles that are added to the operations center using the CasC bundle location, and is not supported if using an HTTP API endpoint or a CLI command to upload a bundle to the operations center. For more information, refer to Configuring bundle availability for controllers. |
||||
jcasc |
list of strings |
Optional. This indicates the bundle contains a |
||||
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.
|
||||
plugins |
list of strings |
Optional. This indicates the bundle contains a |
||||
catalog |
list of strings |
Optional. This indicates the bundle contains a |
||||
items |
list of strings |
Optional. This indicates the bundle contains a |
||||
itemRemoveStrategy |
object |
Optional. This property is composed of the
This property has two sub-elememts:
|
||||
rbac |
list of strings |
Optional. This indicates the bundle contains a |
||||
rbacRemoveStrategy |
object |
Optional. Valid values for this property are:
|
Example bundle.yaml file
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"
jenkins.yaml
This file is the main Configuration as Code configuration file that describes the controller. For more information on how to format this file, refer to the Jenkins Configuration-as-Code plugin documentation.
Example jenkins.yaml file
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. |
plugins.yaml
This file lists all of the plugins to be installed on the controller or the operations center.
The content in the file changes depending on the value of the apiVersion
field.
For CasC bundles using apiVersion:1
, this file should be a list of plugin IDs for CAP and non-CAP
plugins to be installed.
For CasC bundles that use apiVersion:2
, this file has a more complex structure and can include the following:
-
A list of plugin IDs for CAP plugins.
-
Non-CAP plugins, in three different ways:
-
Using only the plugin ID if the Non-CAP plugin is downloaded from the CloudBees Update Center or using a plugin catalog.
-
Using the plugin ID and a URL if the Non-CAP plugin is directly downloaded from an URL.
-
Using the plugin ID, the
groupId
, theversion
, and therepositoyId
if the Non-CAP plugin is downloaded from a Maven repository.
-
CloudBees CI ignores URLs and GAV coordinates for those plugins that are also part of the |
Find many popular plugins and their IDs at the following sites:
For more information, review the Plugin management with CasC page.
plugin-catalog.yaml
This file contains the plugin catalog definitions that can be installed on the controller. The plugin catalog widens the scope of plugins beyond those defined by CAP. Because the plugins.yaml
file only installs plugins within CAP, the plugins-catalog.yaml
file can install plugins outside of CAP on the controller. An optional location can also be specified for plugins that are not available in the standard update centers. For more information on plugin catalogs, refer to Installing non-CAP plugins with plugin catalogs.
Plugins will not be actually installed to the controller unless they are listed in the plugins.yaml file. Transitive dependencies are not automatically added.
|
The plugin catalog feature can be also used separately (non-CasC) on CloudBees CI controllers as described in the documentation. However when using it inside a CasC bundle there are some limitations. For more information, refer to Plugin catalog limitations in CasC. |
Example plugin-catalog.yaml file
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. |
items.yaml
The items.yaml
file contains a list of items to create or update within the instance.
-
By default, items that are present on the instance in the UI but not included in the
items.yaml
file will remain. However, you can change this behavior using differentRemoveStrategy
options. -
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 thevariables.yaml
file in your bundle, you must install the Jenkins Configuration-as-Code plugin.
For more information, refer to Creating items with CasC for controllers.
Property | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
removeStrategy |
object |
Optional. It specifies the strategy to be followed when you apply a new configuration to an existing instance.
Valid values are:
|
||||||||||||||||||||
root |
string |
Optional. Defines the root path for item creation. The path must already exist on the controller instance for the items to be successfully created. For more information, refer to Configuring bundle inheritance with CasC. |
||||||||||||||||||||
items |
list of objects |
Required. The list of items. |
||||||||||||||||||||
kind |
string |
Required. It defines the kind of item created. Supported items:
|
||||||||||||||||||||
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. |
Configure the items.yaml
file to handle variable expressions
To escape variable expressions during an import, apply the cascItemsConfiguration
to the CasC bundle or enable the setting on the System configuration page.
To configure the cascItemsConfiguration
value in the items.yaml
file:
unclassified: cascItemsConfiguration: variableInterpolationEnabledForAdmin: true (1) variableInterpolationEnabledForNonAdmin: true (2)
1 | Set the value to true to allow administrators to use the variable resolution for items imported into the items.yaml file. The value is set to false by default. |
2 | Set the value to true to allow non-adminstrators to use the variable resolution for items imported into the items.yaml file. The value is set to false by default. |
To configure CasC item configuration in the operations center:
-
From the dashboard, select
. -
Navigate to CasC Items configuration.
Figure 1. Enable variable resolution -
Select one of the following:
-
Enable or disable the variable resolution in the item creation for administrator: This allows administrators to use the variable resolution for items imported into the
items.yaml
file. -
Enable or disable the variable resolution in the item creation for non-administrator: This allows non-administrators to use the variable resolution for items in the
items.yaml
file.These settings are disabled by default.
-
-
Select Save.
Example items.yaml file
If a CloudBees CI GitHub Organization is used to configure a repository from a GitHub Enterprise server and you add the server to the Configure System screen, API endpoint is a required field. You must verify that the apiUri property is configured in the items.yaml file. If the GitHub server is not an enterprise server, you can optionally remove the apiUri property from the items.yaml file.
|
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: "pipeline" name: "project-beta-pipeline-job" displayName: "Project Beta Pipeline job" description: "This is Project Beta's Pipeline job!" definition: cpsScmFlowDefinition: scriptPath: "Jenkinsfile" scm: gitSCM: gitTool: "git" userRemoteConfigs: - userRemoteConfig: name: "developer-b" credentialsId: "credentials-id" url: "git@github.com:company/project-beta.git" extensions: - checkoutOption: timeout: 2 - cloneOption: reference: "/workspace/git" noTags: false honorRefspec: false shallow: true timeout: 5 branches: - branchSpec: name: "*/main"
removeStrategy: items: "none" rbac: "sync" items: - kind: "multibranch" name: "project-beta-multibranch-pipeline" displayName: "Project Beta Multibranch Pipeline" description: "This is Project Beta's Multibranch Pipeline job!" orphanedItemStrategy: defaultOrphanedItemStrategy: pruneDeadBranches: true daysToKeep: 3 numToKeep: 4 projectFactory: workflowBranchProjectFactory: scriptPath: "Jenkinsfile" sourcesList: - branchSource: source: github: traits: - gitHubBranchDiscovery: strategyId: 1 - gitHubPullRequestDiscovery: strategyId: 1 - gitHubForkDiscovery: trust: gitHubTrustEveryone: {} strategyId: 1 - headWildcardFilter: excludes: "feature/*" includes: "*" - gitHubSshCheckout: credentialsId: "github-ssh" repoOwner: "company" id: "scm-source-id" repository: "project-alpha" configuredByUrl: true repositoryUrl: "https://github.com/company/project-beta" strategy: allBranchesSame: {}
removeStrategy: items: "none" rbac: "sync" items: - kind: "organizationFolder" name: "project-alpha-github-org" displayName: "Project Alpha GitHub Organization job" description: "This is Project Alpha's Github Organization job!" navigators: - github: traits: - checkoutOptionTrait: extension: checkoutOption: timeout: 5 - cloneOptionTrait: extension: cloneOption: reference: main noTags: false honorRefspec: false shallow: true timeout: 6 repoOwner: "company" projectFactories: - customMultiBranchProjectFactory: factory: customBranchProjectFactory: marker: ".my-marker-file" definition: cpsScmFlowDefinition: scriptPath: "pipelines/default/Jenkinsfile" scm: gitSCM: extensions: - checkoutOption: timeout: 4 gitTool: "git" userRemoteConfigs: - userRemoteConfig: name: "admin-a" credentialsId: "credentials-id" url: "git@github.com:company/project-alpha.git" browser: githubWeb: repoUrl: "git@github.com:company/project-alpha" branches: - branchSpec: name: "*/main" lightweight: false
removeStrategy: items: "none" rbac: "sync" items: - kind: "organizationFolder" name: "project-beta-bitbucket-org" displayName: "Project Beta Bitbucket Organization job" description: "This is Project Beta's Bitbucket Organization job!" navigators: - bitbucket: traits: - bitbucketBranchDiscovery: strategyId: 1 - bitbucketPullRequestDiscovery: strategyId: 1 - bitbucketForkDiscovery: trust: bitbucketTrustTeam: {} strategyId: 1 repoOwner: "company" projectFactories: - workflowMultiBranchProjectFactory: scriptPath: "Jenkinsfile"
removeStrategy: items: "none" rbac: "sync" items: - kind: "cloudbeesTemplatedJob" name: "job-template-alpha" model: "folder1/template"(1) attributes:(2) - value: job-template-alpha(3) key: name - value: the description key: description - value: pwd key: command
1 | The full path to the template. |
2 | Attributes defined in the CloudBees job template. |
3 | The name of the new instance you are creating based on the template. |
removeStrategy: items: "none" rbac: "sync" items: - kind: "cloudbeesTemplatedJob" name: "my-new-job" catalog: "project-alpha-pipeline-template-catalog"(1) model: "template-alpha"(2) attributes:(3) - value: template-alpha(4) key: name - value: the description key: description - value: pwd key: command
1 | The name of the Pipeline Template Catalog that is defined in the catalog.yaml file. |
2 | The name of the template within the Pipeline Template Catalog. |
3 | Attributes defined in the CloudBees job template. |
4 | The name of the new job you are creating based on the template. |
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
removeStrategy: items: "none" rbac: "sync" items: - kind: backupAndRestore name: project-alpha-restore displayName: "Project Alpha restore" description: "This is Project Alpha's restore job!" buildersList: - restoreBuilder: ignoreConfirmationFile: false preserveJenkinsHome: true ignoreDigestCheck: true store: s3Store: bucketName: bucket sse: true bucketFolder: bucketFolder credentialsId: testCredential region: us-east-1 restoreDirectory: /tmp label: agent-for-restore 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 controllers.
|
Property | Type | Description | ||||
---|---|---|---|---|---|---|
removeStrategy |
object |
Optional. It specifies the strategy to be followed when you apply a new configuration to an existing instance.
Valid values for this property are:
|
||||
rbac |
string |
Required. Specifies how an existing configuration is handled when a new configuration is applied.
|
||||
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 with the placeholder ${}
, for example ${team_name}
.
Variables are not supported for the plugins.yaml
and plugin-catalog.yaml
files.
To escape a string from variable substitution, the literal ^ must be placed in front of the expression. For example, ^${variableName} resolves to ${variableName} . For more information, refer to Passing secrets through variables.
|
Exporting a CasC configuration
You can export a CasC configuration from an existing controller to create a template bundle. You can use the template bundle to set up a new controller and connect it to the operations center with Configuration as Code. However, the exported configuration should only be used as a starting point 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.
|
|
To prevent the environment configuration from being leaked, the variable expressions within exports are escaped. In the following pipeline example:
pipeline { agent any environment { greeting = 'Hello, World!' } stages { stage('Print Greeting') { steps { echo "${env.greeting}" sh 'echo ${GLOBAL_ENV}' } } } }
The export renders as follows:
kind: pipeline name: testWithVars concurrentBuild: true definition: cpsFlowDefinition: sandbox: true script: |- pipeline { agent any environment { greeting = 'Hello, World!' } stages { stage('Print Greeting') { steps { echo "^${env.greeting}" (1) sh 'echo ^${GLOBAL_ENV}' } } } } description: '' disabled: false displayName: testWithVars1 resumeBlocked: false
1 | The user must remove the ^ characters where it applies. |
Prerequisites
The following software and plugins must be installed to export the current configuration:
-
If using CloudBees CI 2.249.3.1 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.2 - 1.41
-
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Client plugin, version 1.44 or later
Exporting the current configuration
To export the current configuration from an existing controller:
-
Create a test controller in your cluster using the UI.
-
Configure the controller’s plugins and global configuration using the UI.
-
Optionally, configure a plugin catalog using the UI.
-
From the controller, select Manage Jenkins in the left pane.
-
Select CloudBees Configuration as Code export and update.
Figure 2. CloudBees Configuration as Code export and update -
Select Current configuration.
Figure 3. 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
,plugin-catalog.yaml
,rbac.yaml
, anditems.yaml
files. If you do not include these files in your bundle, do not list them in yourbundle.yaml
file.If CAP/Beekeeper is disabled on the controller, the exported configuration includes the
plugins.yaml
andplugin-catalog.yaml
files, but they contain one of the following warning messages:-
plugin-catalog.yaml
message:Cannot export catalog because CAP is not enabled
-
plugins.yaml
message:Cannot export plugins because CAP is not enabled
-
-
Save the files using the following file names:
-
bundle.yaml
-
jenkins.yaml
-
plugins.yaml
-
plugin-catalog.yaml
-
rbac.yaml
-
items.yaml
-
variables.yaml
For the bundle to be valid, the above files must use these exact filenames.
-
-
After creating a bundle based on the exported configuration, add the bundle to the operations center, configure the bundle availability, and set up a new controller. For more information, refer to:
-
Setting up a client controller using CasC
You must remove the obsolete operationsCenterRootAction
connection details from thejenkins.yaml
file before connecting it to the operations center so new connection details can be established for the new controller. Connection details are controller-specific, and cannot be shared between controllers. If you release a client controller, the connection details also change. Do not include them unless you know what you are doing. IfoperationsCenterRootAction
is not present in thejenkins.yaml
file, the operations center creates it in the background.
Remove the license:
section from thejenkins.yaml
file if the controller is connected to an operations center, so the operations center can automatically update the license. -
Delete the original test controller created in the UI; it is no longer needed.
If the controller has not been configured a CasC bundle, the exported bundle uses Review how inheritance can affect this |
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: {}
Composing CasC bundles
There are several options for composing CasC bundles. You can compose:
Single bundle
A single CasC bundle is composed of individual YAML files stored in a folder and the bundle is deployed to the operations center.
For more information, refer to Adding controller CasC bundles to the operations center.
Single bundle with folders and subfolders
Configuration settings can be stored in individual YAML files, and the files stored within folders and subfolders in the bundle.
CloudBees recommends that each YAML file contain only unique configuration elements that do not override configuration elements in other YAML files.
The Plugin Catalog does not support storing configuration settings in individual YAML files. |
Avoiding YAML file overrides
An override in a YAML file does not include the whole file but properties within the YAML file. For example, if items1.yaml
defines a property and items2.yaml
defines the same property then:
-
Properties not defined in
items2.yaml
will have the same value as properties fromitems1.yaml
. -
Properties defined in
items2.yaml
will override the value of properties fromitems1.yaml
.
|
To prevent undesired item overrides, YAML files are read as follows:
-
If files are listed in the section, they are read in that order, so the last file overrides the first.
-
If the folder containing the files is referenced instead of listing them, the files are read in alphanumeric order.
-
If there is inheritance, child files override their parent files.
Example bundle with folders
In this example, a configurations
folder contains individual YAML files:
/oc-bundles └── bundle-1 ├── bundle.yaml ├── configurations │ ├── jenkins.yaml │ └── security.yaml ├── plugins.yaml ├── plugin-catalog.yaml ├── items.yaml ├── rbac.yaml └── variables.yaml
The bundle.yaml
file lists each individual YAML file:
id: "bundle-1" version: "1" apiVersion: "1" description: "My CloudBees Configuration as Code (CasC) bundle" jcasc: - "configurations/jenkins.yaml" - "configurations/security.yaml" plugins: - "plugins.yaml" catalog: - "plugin-catalog.yaml" items: - "items.yaml" rbac: - "rbac.yaml" variables: - "variables.yaml"
Example bundle with subfolders
In this example, the configurations
folder contains a jenkins
subfolder, and the jenkins
subfolder contains the individual YAML files:
/oc-bundles └── bundle-1 ├── bundle.yaml ├── configurations │ └── jenkins │ └── jenkins.yaml │ └── security.yaml ├── plugins.yaml ├── plugin-catalog.yaml ├── items.yaml ├── rbac.yaml └── variables.yaml
This allows you to add or remove YAML files from the subfolder without requiring that you update the bundle.yaml
file:
id: "bundle-1" version: "1" apiVersion: "1" description: "My CloudBees Configuration as Code (CasC) bundle" jcasc: - "configurations/jenkins/" plugins: - "plugins.yaml" catalog: - "plugin-catalog.yaml" items: - "items.yaml" rbac: - "rbac.yaml" variables: - "variables.yaml"
Multiple bundles
Multiple bundles can also be deployed to the operations center.
For more information, refer to Adding controller CasC bundles to the operations center.
Example folders for multiple bundles
/oc-bundles ├── bundle-1 │ ├── bundle.yaml │ ├── jenkins.yaml │ ├── plugins.yaml │ ├── plugin-catalog.yaml │ ├── items.yaml │ ├── rbac.yaml │ └── variables.yaml └── bundle-2 ├── bundle.yaml ├── jenkins.yaml ├── plugins.yaml ├── plugin-catalog.yaml ├── items.yaml ├── rbac.yaml └── variables.yaml
Multiple bundles with bundle inheritance
"Child" bundles can also be configured to inherit from a "parent" bundle.
For more information, refer to Configuring bundle inheritance with CasC.
Example folder structure for bundle inheritance
In this example, there is a parent bundle: bundle-global
. There are also two child bundles: bundle-1
and bundle-2
. The child bundles use the same jenkins.yaml
file and plugins.yaml
file as the parent bundle, but include unique items in their items.yaml
files.
/oc-bundles ├── bundle-global │ ├── bundle.yaml │ ├── jenkins.yaml │ ├── plugins.yaml │ └── items.yaml ├── bundle-1 │ ├── bundle.yaml │ └── items.yaml └── bundle-2 ├── bundle.yaml └── items.yaml