Creating items with CasC for controllers

13 minute readScalabilityAutomation

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.

Configure variable resolution for items in a CasC bundle

You can configure variable resolution for items in a bundle by doing one of the following:

  • Configure the cascItemsConfiguration value in the jenkins.yaml file.

  • Enable the Enable or disable the variable resolution in the item creation for administrator on the System Configuration page in the UI.

Configure the jenkins.yaml file to handle variable resolution in the items.yaml file

Set variable resolutions for items in a bundle by configuring the cascItemsConfiguration value in the jenkins.yaml file.

unclassified: cascItemsConfiguration: variableInterpolationEnabledForAdmin: true (1) variableInterpolationEnabledForNonAdmin: true (2)
1 Set the variableInterpolationEnabledForAdmin value to true to allow administrators to use the variable resolution for items in the items.yaml file. The value is set to false by default.
2 Set the variableInterpolationEnabledForNonAdmin value to true to allow non-adminstrators to use the variable resolution for items in the items.yaml file. The value is set to false by default.

The variableInterpolationEnabledForNonAdmin setting is ignored if the variable resolution is not allowed (false) for administrators. For example:

  • If variableInterpolationEnabledForAdmin is false for administrators, then the variable resolution is also not allowed for non-administrators even if variableInterpolationEnabledForNonAdmin is set to true.

  • If variableInterpolationEnabledForAdmin is true for administrators, then variable resolution is allowed for non-administrators if variableInterpolationEnabledForNonAdmin is also set to true.

Configure the variable resolution in the controller

To enable variable resolution in controllers, configure the CasC item configuration setting on the System Configuration page.

To configure CasC item configuration in the controller:

  1. From the dashboard, select Manage Jenkins  System.

  2. Navigate to CasC Items configuration.

    Enable variable resolution
    Figure 1. Enable variable resolution
  3. Select one of the following:

    1. Enable or disable the variable resolution in the item creation for administrator: This allows administrators to use the variable resolution for items imported in the item.yaml file. This setting is disabled by default.

    2. 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. This setting is disabled by default.

      The Enable or disable the variable resolution in the item creation for non-administrator setting is ignored if the variable resolution is not allowed (disabled) for administrators. For example:

      • If Enable or disable the variable resolution in the item creation for administrator is disabled, then the variable resolution is also not allowed for non-administrators even if Enable or disable the variable resolution in the item creation for non-administrator is selected.

      • If Enable or disable the variable resolution in the item creation for administrator is selected, then variable resolution is allowed for non-administrators if Enable or disable the variable resolution in the item creation for non-administrator is also selected.

  4. Select Save.

Escape variable expressions

To prevent exposure of variable resolution values and potentially leaking secrets, items.yaml files in a CasC bundle can escape variable expressions.

In the example below, the items.yaml contains a folder with a display name escaped: ^${testkey} and a folder with the display name variable: ${testkey}.

items: - kind: folder name: b displayName: "escaped: ^${testkey}" - kind: folder name: a displayName: "variable: ${testkey}"

The variables.yaml contains variable named testkey: testvalue.

variables: - testkey: testvalue

When the variable resolution setting is enabled in the UI or the jenkins.yaml file, CasC removes the circumflex (^) character and treats the following $ as plain text. In the UI, the first folder name is displayed without ^ character. For the second folder’s display name, the variable is substituted with its value.

folder with escaped character
Figure 2. Folder name without the ^ charater when the variable resolution is enabled

When the variable resolution setting is disabled, CasC treats the displayName values as plain text in both cases. In the UI, the folder names displays all the characters of the configured strings including the circumflex (^).

folder name with all characters displayed
Figure 3. Folder name with all charaters displayed when the variable resolution is disabled

Supported items using CasC

The following items are supported using CasC. You must install the prerequisite CloudBees CI 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 CloudBees Role-Based Access Control Plugin.
Table 1. Supported item types and prerequisites
Item type Prerequisites

Folders with limited fields

Folders with extended fields (recommended)

Freestyle jobs

Pipeline jobs

Multibranch Pipeline jobs

GitHub Organization

Bitbucket Team/Project

Instance based on a CloudBees template

Backup and restore

Example CasC configuration bundle with items

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"

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.

Example plugins.yaml file

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

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 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.
Folders with limited fields
Folders with extended fields
Freestyle job
Pipeline job
Multibranch Pipeline job
GitHub Organization
Bitbucket Team/Project
Instance based on a CloudBees template
Job based on a Pipeline Template Catalog
Backup
Restore
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

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

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:

Exporting the CasC item

To export a CasC item:

  1. Ensure you are signed in to the controller as a user with the Administer permission.

  2. Create a new item in the UI and configure it. Or, if you have an existing item that is already configured, you can skip this step.

  3. From the controller dashboard, select the item, and then select Export CasC item in the left pane.

  4. From the Export CasC item screen, select Download YAML to export the item as a YAML snippet.

  5. Add the exported YAML snippet to your items.yaml file.

  6. Add the removeStrategy, items, and rbac required properties to your items.yaml file, if not already present. For more information, refer to items.yaml.

  7. If you created a new item in the UI and it is no longer needed, you can delete it.

Creating items based on CloudBees templates

You can use CasC to create an item based on a CloudBees template.

This can be useful if you want to:

Creating an instance based on a CloudBees template

In the UI, you can create a CloudBees template and create a new instance based on the template. You can then export the instance in YAML format and use this to create new instances using CasC. The following example illustrates how to create a job based on a CloudBees job template.

To create a job based on a CloudBees template:

  1. Ensure you are signed in to the controller as a user with the Administer permission.

  2. Create a CloudBees job template. For more information, refer to CloudBees Template plugin.

  3. Create a job based on the template and specify the required attributes.

  4. Select Export CasC item to export the job in YAML format. For more information, refer to Exports of individual CasC items.

  5. Copy the exported job and paste it into the controller’s items.yaml file. For example:

    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.
  6. Update the controller CasC bundle.

    Select Reload Configuration to apply the new configuration without restarting the controller.

Creating a Pipeline Template Catalog and job using CasC

You can export the current CasC configuration for the controller to create a Pipeline Template Catalog and job using CasC.

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.

To create a job based on a Pipeline Template Catalog:

  1. Ensure you are signed in to the controller as a user with the Administer permission.

  2. Create a Pipeline Template Catalog and add a template to it. For more information, refer to Pipeline Templates.

  3. Create a new job based on the template in the Pipeline Template Catalog and specify the required attributes.

  4. Export the current configuration from the controller.

  5. Open the controller’s jenkins.yaml file from the exported configuration.

  6. Copy the globalCloudBeesPipelineTemplateCatalog properties and paste them into the jenkins.yaml file in the controller CasC bundle. For example:

    globalCloudBeesPipelineTemplateCatalog: (1) catalogs: - branchOrTag: "main" scm: git: credentialsId: "credentials-id" id: "cf504eg3-4y5d-34w2-97b1-2q7xt2nm9731" (2) remote: "git@github.com:company/project-alpha.git" updateInterval: "1d"
    1 Required if using CasC to create a job based on a Pipeline Template Catalog.
    2 Required property that defines the unique ID for the SCM repository where the Pipeline Template Catalog is stored.
  7. Open the controller’s items.yaml file from the exported configuration.

  8. Copy the CloudBees template item and paste it into the items.yaml file in the controller CasC bundle. For example:

    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.
  9. Update the controller CasC bundle.

    Select Reload Configuration to apply the new configuration without restarting the controller.