Configuration as Code allows you to create items if the items.yaml
file is included in the configuration bundle.
You can export individual CasC items or export all item configurations from an existing instance. However, the exported file should only be used as a starting point, as it may require modifications and adjustments to make it production-ready. For more information, refer to Exports of individual CasC items and Exporting a CasC configuration. |
Supported items using CasC
The following items are supported using CasC. You must install the prerequisite CloudBees Jenkins Platform software and plugins based on the item type you are creating.
If using RBAC to define roles and groups for items, you must also install the Configuration as Code plugin and Operations Center Server Role Based Access Control plugin. |
Item type | Prerequisites |
---|---|
Folders with limited fields |
|
Folders with extended fields (recommended) |
|
Freestyle jobs |
|
Cluster operations |
|
Client controller |
|
Shared agent |
|
Shared cloud |
|
Backup |
|
Example CasC configuration bundle with items
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"
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:
location:
url: https://operations-center:8888/ (3)
bundleStorageService: (4)
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 | Required to create client controller items. The url is the operations center URL. |
4 | 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:
# 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 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: 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
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". |
Exports of individual CasC items
You can export an existing item as a YAML snippet and add it to the items.yaml
file. However, the exported item should only be used as a starting point, as it may require modifications and adjustments to make it production-ready.
Exporting an individual CasC item is not supported for the auto-generated children of folder-type items for Multibranch Pipeline jobs, GitHub Organizations, and Bitbucket Teams/Projects. |
Prerequisites
The following software and plugins must be installed to export the item:
-
If using CloudBees Jenkins Platform 2.303.3.3: CloudBees CasC API Plugin (Deprecated), version 1.41 or later
-
If using CloudBees Jenkins Platform 2.319.1.5 or later:
-
For controllers:
-
CloudBees CasC Items API Plugin, version 1.1.1 or later
-
CloudBees CasC Items Commons Plugin, version 1.0 or later
-
CloudBees CasC Items Controller Plugin, version 1.1 or later
-
-
For operations center:
-
CloudBees CasC Items API Plugin, version 1.1.1 or later
-
CloudBees CasC Items Commons Plugin, version 1.0 or later
-
CloudBees CasC Items Server Plugin, version 1.1 or later
-
-
Exporting the CasC item
To export a CasC item:
-
Verify you are signed in to the operations center as a user with the Administer permission.
-
Create a new item in the UI and configure it. Skip this step if you have an existing item that is already configured.
-
From the operations center dashboard, select the item and then select Export CasC item in the left pane.
-
From the Export CasC item screen, select Download YAML to export the item as a YAML snippet.
-
Add the exported YAML snippet to your
items.yaml
file. -
Add the
removeStrategy
,items
, andrbac
required properties to youritems.yaml
file, if not already present. For more information, refer to items.yaml. -
If you created a new item in the UI and it is no longer needed, you can delete it.
Creating a new controller item using CasC for the operations center
You can export the current configuration for the operations center to create a new controller item using CasC. The following steps assume:
-
You have set up an operations center instance and configured it using CasC.
-
You have set up a controller.
-
If the controller is configured using CasC, you have also created a controller CasC bundle, added the CasC bundle to the operations center, and configured the controller bundle availability.
If the controller is configured using a CasC bundle, you can add the cloudBeesCasCServer
property to the operations centerjenkins.yaml
file. When thevisibility
is set totrue
, 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.The credentials from the operations center cannot be used during the initial startup of the controller. If the credentials are required during the initial startup of the controller before the connection has been created, you must define the credentials in the controller.
Adding a client controller item to the operations center CasC bundle
To add a client controller item to the operations center CasC bundle:
-
Ensure you are signed in to the operations center as a user with the Administer permission.
-
Export the current configuration from the operations center.
-
Open the operations center
items.yaml
file from the exported configuration. -
Copy the
clientController
item from the exported configuration and paste it into theitems.yaml
file in the operations center CasC bundle. -
Specify a unique
name
for the controller. For example:name: "client-controller-beta"
-
If configuring the controller to use CasC, specify the CasC
bundle
that should be assigned to the controller. For example:- configurationAsCode: bundle: bundle-2
-
You must add the operations center URL to the
jenkins.yaml
file to create client controllers. Open the operations centerjenkins.yaml
file in the operations center CasC bundle and add thelocation
properties to it. For example:unclassified: location: url: https://operations-center:8888/
-
Update the operations center CasC bundle.
Select Reload Configuration to apply the new configuration without restarting the operations center. -
From the operations center dashboard, select the down arrow to the right of your controller’s name, and then select Configure.
Figure 1. Controller dropdown menu -
Verify the controller settings are correct. If you assigned a CasC bundle to the controller, scroll down to Configuration as Code (CasC) and verify the controller CasC bundle that you specified in the operations center
items.yaml
file is assigned to the controller. -
Configure the client controller with the casc-bundle-link.yml file.