The configuration of the operations center is described in a collection of YAML files referred to as a CasC bundle.
CloudBees does not recommend adding your CloudBees CI license or certificate to the CasC bundle for the operations center because these values are hardcoded. If you do add a license key or certificate to your CasC bundle, you must manually ensure they are always up-to-date, because they will be the only license and certificate the operations center can read. |
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.
-
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.
For the bundle to be valid, the above files must use these exact filenames. |
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.
|
bundle.yaml
The bundle.yaml
file is an index file that describes the bundle and references the other files in the bundle.
Property | Type | Description |
---|---|---|
id |
string |
Required. This bundle’s unique identifier.
NOTE: The |
version |
string |
Required. The bundle’s version. This value should be incremented whenever the bundle is modified. |
apiVersion |
string |
Required. This is the bundle’s API version. The expected value is "1". |
description |
string |
Optional. A helpful description of the bundle. |
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 |
items |
list of strings |
Optional. This indicates the bundle contains a |
rbac |
list of strings |
Optional. This indicates the bundle contains a |
Example bundle.yaml file
id: "bundle-1"
version: "1"
apiVersion: "1"
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"
jenkins.yaml
This file is the main CasC configuration file that describes the operations center. For more information on how to format this file, refer to the Jenkins Configuration-as-Code plugin documentation.
Example jenkins.yaml file
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. |
plugins.yaml
This file lists all plugins that should be installed on the controller or the operations center. Plugins not included in the CloudBees Assurance Program (CAP) should be added via a Plugin Catalog. For more information, see [_plugin_catalog_yaml].
The contents of this file should be a list of plugin IDs. Find many popular plugins and their IDs at the following sites:
Example plugins.yaml file
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"
items.yaml
The purpose of the items.yaml
file is to describe the items to be created in the instance.
For more information, refer to Creating items with CasC for the operations center.
|
Property | Type | Description |
---|---|---|
removeStrategy |
object |
Required. It specifies the strategy followed to handle an existing configuration when a new configuration is applied. |
items |
string |
Required. The only supported value is NONE. No item is going to be removed in the instance as part of the creation process. |
rbac |
string |
Required. Specifies how an existing configuration is handled when a new configuration is applied.
|
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. |
Example 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: clusterOpProject
name: "project-alpha-cluster-operations"
displayName: "Project Alpha - Cluster operations"
description: "These are Project Alpha's cluster operations!"
disabled: false
concurrentBuild: true
operations:
- masterClusterOperation:
failureMode: IMMEDIATELY
clusterOpSteps:
- backupClusterOpStep:
subjects:
- buildRecordSubject: {}
- jobConfigurationSubject: {}
format:
zipFormat: {}
retentionPolicy:
exponentialDecayRetentionPolicy: {}
safeDelaySeconds: 10
store:
s3Store:
bucketName: ' mybucket'
sse: true
bucketFolder: somefolder
credentialsId: 'my-aws-credentials-id'
region: us-east-1
timeoutSeconds: 0
itemSource:
jenkinsRootItemSource: {}
filters:
- isMasterOnlineFilter: {}
inParallel: 0
noRetries: 0
removeStrategy:
items: "none"
rbac: "sync"
items:
- kind: managedController
displayName: "managed-controller-alpha"
name: "managed-controller-alpha"
description: "This is Project Alpha's managed controller!"
groups:
- name: "Project Alpha Developers"
members:
users:
- developer-1
roles:
- name: developer
properties:
- configurationAsCode:
bundle: bundle-1
- healthReporting:
enabled: false
- owner:
delay: 5
owners: ''
- envelopeExtension:
allowExceptions: false
- sharedConfigurationOptOut:
optOut: false
- licensing:
strategy:
perUserLicensingStrategy: {}
configuration:
kubernetes:
allowExternalAgents: false
terminationGracePeriodSeconds: 1200
#image: cloudbees/mc-foo-image # uncomment to use a non-default image
memory: 3072 (1)
fsGroup: '1000'
cpus: 1.0
readinessTimeoutSeconds: 5
livenessInitialDelaySeconds: 300
readinessInitialDelaySeconds: 30
clusterEndpointId: default
disk: 50
readinessFailureThreshold: 100
livenessTimeoutSeconds: 10
domain: managed-controller-alpha
livenessPeriodSeconds: 10
javaOptions: -DfooSystemProperty="foo" -Dbar="bar"
yaml: |-
---
kind: StatefulSet
metadata:
labels:
my-label: my-value
1 | Some settings, such as controller memory, require the controller to be re-provisioned for the setting to take effect. |
removeStrategy:
items: "none"
rbac: "sync"
items:
- kind: clientController
displayName: "client-controller-beta"
name: "client-controller-beta"
description: "This is Project Beta's client controller!"
groups:
- name: "Project Beta Developers"
members:
users:
- developer-1
roles:
- name: developer
properties:
- configurationAsCode:
bundle: bundle-2
- healthReporting:
enabled: false
- owner:
delay: 5
owners: ''
- envelopeExtension:
allowExceptions: false
- sharedConfigurationOptOut:
optOut: false
- licensing:
strategy:
perUserLicensingStrategy: {}
- webSocket:
enabled: true
removeStrategy:
items: "none"
rbac: "sync"
items:
- kind: "sharedAgent"
displayName: "Shared Agent for this cluster"
name: "shared-agent-1"
description: "Shared Agent for this cluster"
remoteFS: "/tmp/remote"
properties:
- sharedAgent:
customizers:
- envVars:
value:
SKIP_RELEASE: "TRUE"
JENKINS_VERSION: "2.303"
- toolLocation:
value:
- name: "git"
type: "git"
home: "/usr/local/git"
- name: "maven3"
type: "mvn"
home: "/usr/local/mvn"
labels: "ubuntu"
launcher:
inboundAgent:
webSocket: true
workDirSettings:
remotingWorkDirSettings:
internalDir: "/path/to/directory"
disabled: false
failIfWorkDirIsMissing: true
workDirPath: "/path/to/directory"
agentStartupOptions: "-noCertificateCheck"
vmargs: "-Xms2G -Xmx2G"
tunnel: "192.1.1.45:22"
mode: EXCLUSIVE
numExecutors: 10
retentionStrategy:
sharedNodeRetentionStrategy: {}
removeStrategy:
items: "none"
rbac: "sync"
items:
- kind: "sharedCloud"
displayName: "Shared Cloud for this cluster"
name: "shared-cloud-1"
description: "Shared Cloud for this cluster"
properties:
- sharedCloud:
customizers:
- envVars:
value:
SKIP_RELEASE: "TRUE"
JENKINS_VERSION: "2.303"
- toolLocation:
value:
- name: "git"
type: "git"
home: "/usr/local/git"
- name: "maven3"
type: "mvn"
home: "/usr/local/mvn"
cloud:
inboundAgents:
mode: EXCLUSIVE
numExecutors: 10
remoteFS: "/path/to/directory"
labels: "ubuntu"
launcher:
inboundAgent:
webSocket: true
workDirSettings:
remotingWorkDirSettings:
internalDir: "/path/to/directory"
disabled: false
failIfWorkDirIsMissing: true
workDirPath: "/path/to/directory"
agentStartupOptions: "-noCertificateCheck"
vmargs: "-Xms2G -Xmx2G"
tunnel: "192.1.1.45:22"
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
rbac.yaml
The purpose of the rbac.yaml
file is to describe the role-based access control (RBAC) groups and roles defined at the root level.
For more information, refer to Configuring RBAC with CasC for the operations center.
|
Property | Type | Description |
---|---|---|
removeStrategy |
object |
Required. It specifies the strategy followed to handle an existing configuration when a new configuration is applied. |
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". |
Exporting a CasC configuration
You can export a CasC configuration from an existing operations center instance to create a template bundle. You can use the template bundle to set up a new operations center instance using CasC. However, the exported configuration should not be used as is 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.
|
Prerequisites
The following plugins must be installed to export the current configuration:
-
If using CloudBees CI 2.289.3.2 - 2.303.3.3: CloudBees CasC API Plugin (Deprecated), version 1.14 - 1.41
-
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Client Plugin, version 1.44 or later
-
Configuration as Code plugin
Exporting the current configuration
To export the current configuration from a test operations center instance:
-
Install operations center as a test instance.
-
Configure the plugins and global configuration using the UI.
-
Select Manage Jenkins in the left pane.
-
Select CloudBees Configuration as Code export and update.
Figure 1. CloudBees Configuration as Code export and update -
Select Current configuration.
Figure 2. 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
,items.yaml
, andrbac.yaml
files. If you do not include these files in your bundle, do not list them in yourbundle.yaml
file. -
Save the files using the following file names:
-
bundle.yaml
-
jenkins.yaml
-
plugins.yaml
-
items.yaml
-
rbac.yaml
-
variables.yaml
For the bundle to be valid, the above files must use these exact filenames. If you rename these files, you must update them in your bundle.yaml
file.
-
-
Uninstall the original operations center test instance; it is no longer needed.
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: {}