Configure RBAC with CasC for controllers

16 minute readScalabilityAutomation

Configure global Role-Based Access Control (RBAC) by adding the rbac.yaml file to the configuration bundle. Additionally, the authorizationStrategy attribute must be added to the jenkins.yaml file.

Prerequisites

The following software and plugins must be installed to use RBAC with CasC:

Required setup

Define groups and roles at the controller-level using the Configuration as Code rbac.yaml file.

  • Variable resolution: To use variables within the RBAC configuration file (rbac.yaml), configure variable resolution for items within a CasC bundle. For more information, refer to Configuring variable resolution for the RBAC configurations in a CasC bundle

  • Controller authorization strategy: To apply RBAC settings (rbac.yaml) to a controller using CasC, the controller’s authorization strategy must not be inherited from operations center. For more information, see Configuring the controller authorization strategy.

  • User management: Users need to be created in your CloudBees CI system either by an identity provider (like LDAP) or manually. The examples below assume the users exist.

  • Item management: To apply RBAC groups and/or roles to items, the CasC configuration bundle must include an items.yaml file with the defined items. For more information, refer to Create items with CasC for controllers.

Configuring variable resolution for the RBAC configurations in a CasC bundle

CasC variable resolution refers to the ability to use variables within configuration files (such as rbac.yaml) to insert and substitute values during the creation of roles and groups in CloudBees CI. This feature allows administrators or non-administrators to manage configurations by using placeholders that can be replaced with actual values at runtime.

Variable resolution can be enabled or disabled for administrators and non-administrators, with the non-administrator setting being dependent on the administrator setting.

To 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 variable resolution for CasC administrator on the System Configuration page in the UI.

Variable resolution can also be configured for items imported from the items.yaml file. For more information, refer to Configure variable resolution for items in a CasC bundle.

Configure the jenkins.yaml file to handle variable resolution in the rbac.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 rbac.yaml file. The value is set to false by default.
2 Set the variableInterpolationEnabledForNonAdmin value to true to allow non-administrators to use the variable resolution for items in the rbac.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 Variable Resolution Configuration setting on the System configuration page.

To configure the variable resolution in the controller:

  1. Navigate to CasC Variable Resolution Configuration.

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

    1. Enable or disable variable resolution for CasC administrator: This allows administrators to use the variable resolution for RBAC configurations imported from the rbac.yaml files. This setting is disabled by default.

    2. Enable or disable variable resolution for non-administrator: This allows non-administrators to use the variable resolution for RBAC configuations imported from the rbac.yaml files. This setting is disabled by default.

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

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

      • If Enable or disable variable resolution for CasC administrator is enabled, then variable resolution is allowed for non-administrators if Enable or disable variable resolution for non-administrator is also selected.

  3. Select Save.

Escapte variable expressions

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

In the example below, the rbac.yaml contains a group with a display name ${ADMINISTRATORS_GROUP_NAME} and a role permission with the display name ${ADMINISTER_PERMISSION}.

removeStrategy: rbac: "sync" groups: - name: "${ADMINISTRATORS_GROUP_NAME}" members: users: - "me@myorg.com" roles: - name: "administer" grantedAt: "current" propagates: "false" roles: - name: "administer" filterable: "false" permissions: - "${ADMINISTER_PERMISSION}"

The varibles.yaml contains variables names variables ADMINISTRATORS_GROUP_NAME: Administrators and ADMINISTER_PERMISSION: hudson.model.Hudson.Administer.

variables: - ADMINISTRATORS_GROUP_NAME: Administrators - ADMINISTER_PERMISSION: hudson.model.Hudson.Administer

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 ^ character 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 characters displayed when the variable resolution is disabled

Configuring the controller authorization strategy

To apply RBAC settings (rbac.yaml) to an individual controller using Configuration as Code, the controller’s authorization strategy must not be inherited from the operations center.

If groups and roles are defined in the operations center or if RBAC is only used with the items.yaml file, you do not need to opt out of inheriting the operations center’s authorization strategy.

To configure the controller authorization strategy:

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

  2. From the operations center dashboard, in the left pane, select Manage Jenkins.

  3. Select Configure Global Security.

  4. Scroll down to Client controller security and select Allow client controllers to opt-out.

  5. Select Save.

    For more information on how to customize the authorization strategy for an individual controller, refer to Configuring SSO in the operations center.
  6. From the operations center dashboard, select the down arrow to the right of your controller’s name, and then select Configure.

    Controller dropdown menu
    Figure 4. Controller dropdown menu
  7. Scroll down to Security Setting Enforcement and select either Enforce Authentication only or Opt out of all security enforcement.

    For more information on how to customize the authorization strategy for an individual controller, refer to Configuring options for individual controllers.

Exporting RBAC configurations

You can export Role-Based Access Control (RBAC) configurations from an existing controller. For more information, refer to Exporting a CasC configuration.

The exported file should be used as a starting point, as it may require modifications and adjustments to make it production-ready.

Example CasC configuration bundle with items

Example bundle.yaml file

bundle.yaml for a controller

id: "remove-bundle" version: "1" apiVersion: "1" description: "CasC bundle with removeStrategy in descriptor" allowCapExceptions: true availabilityPattern: "folder1/.*" parent: "bundle-global" jcasc: - "jenkins.yaml" jcascMergeStrategy: "errorOnConflict" plugins: - "plugins.yaml" catalog: - "plugin-catalog.yaml" itemRemoveStrategy: items: "remove-all" rbac: "sync" rbacRemoveStrategy: "sync" items: - "items.yaml" rbac: - "rbac.yaml" variables: - "variables.yaml"

bundle.yaml for an operations center

id: "bundle-1" version: "1" apiVersion: "2" description: "My CloudBees Configuration as Code (CasC) bundle" jcasc: - "jenkins.yaml" jcascMergeStrategy: "errorOnConflict" plugins: - "plugins.yaml" items: - "items.yaml" rbac: - "rbac.yaml" variables: - "variables.yaml"

Example jenkins.yaml file

jenkins.yaml for a controller

jenkins: systemMessage: "Controller configured using CloudBees CasC" numExecutors: 0 securityRealm: ldap: configurations: - displayNameAttributeName: "cn" groupMembershipStrategy: fromGroupSearch: filter: "member={0}" groupSearchBase: "ou=Groups" inhibitInferRootDN: false managerDN: "cn=admin,dc=example,dc=org" managerPasswordSecret: ${LDAP_MANAGER_PASSWORD} rootDN: "dc=example,dc=org" server: "ldap://ldap-openldap:389" userSearchBase: "ou=People" disableMailAddressResolver: false groupIdStrategy: "caseInsensitive" userIdStrategy: "caseInsensitive" authorizationStrategy: "cloudBeesRoleBasedAccessControl"(1) globalCloudBeesPipelineTemplateCatalog:(2) catalogs: - branchOrTag: "main" scm: git: credentialsId: "credentials-id" id: "cf504eg3-4y5d-34w2-97b1-2q7xt2nm9731"(3) remote: "git@github.com:company/project-alpha.git" updateInterval: "1d"
1 Required to use CloudBees RBAC configured using CasC.
2 Required if using CasC to create a job based on a Pipeline Template Catalog.
3 Required property that defines the unique ID for the SCM repository where the Pipeline Template Catalog is stored.

jenkins.yaml for an operations center

jenkins: systemMessage: "Operations center configured using CloudBees CasC" numExecutors: 0 securityRealm: ldap: configurations: - displayNameAttributeName: "cn" groupMembershipStrategy: fromGroupSearch: filter: "member={0}" groupSearchBase: "ou=Groups" inhibitInferRootDN: false managerDN: "cn=admin,dc=example,dc=org" managerPasswordSecret: ${LDAP_MANAGER_PASSWORD} rootDN: "dc=example,dc=org" server: "ldap://ldap-openldap:389" userSearchBase: "ou=People" disableMailAddressResolver: false groupIdStrategy: "caseInsensitive" userIdStrategy: "caseInsensitive" authorizationStrategy: "cloudBeesRoleBasedAccessControl"(1) security: securitySettingsEnforcement: global: realmAndAuthorization: canCustomMapping: false canOverride: true defaultMappingFactory: "restrictedEquivalentRAMF" controllerExecutorCount: enforce: canOverride: false count: 0 cloudBeesCasCServer: visibility: true(2) unclassified: cascAutoControllerProvisioning: provisionControllerOnCreation: true(3) fireAndForget: true(4) initialDelay: 15 (5) timeout: 600(6) duration: 60(7) location: url: https://operations-center:8888/(8) bundleStorageService:(9) activated: true activeBundle: name: "local-folder" retriever: SCM: scmSource: git: id: "acf88621-05a0-4d50-9166-d7767868dc43" remote: "https://github.com/my-company/repo.git" traits: - "gitBranchDiscovery" pollingPeriod: 0 purgeOnDeactivation: false
1 Required to use CloudBees RBAC configured using CasC.
2 Optional if using the items.yaml file to create a controller item. When visibility is set to true, all CasC bundles that do not have an availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.
3 When provisionControllerOnCreation is set to true, all managed controller items are provisioned automatically after they are created using CasC.
4 When fireAndForget is set to true, the automatic provisioning process starts immediately, and does not wait for the controller to be connected.
5 The amount of time, in seconds, to wait before starting the automatic provisioning process.
6 The amount of time, in seconds, to complete the automatic provisioning process. If fireAndForget is set to false, this timeout may prevent queued provisioning requests from being blocked.
7 The provisioning duration, in seconds. After the initial delay, controllers are provisioned at random in batches of 20 controllers, for this time period. Increase this value to increase the amount of time between controller provisioning requests. If provisioning more than 20 controllers, the provisioning process will exceed the specified duration.
8 Required to create client controller items. The url is the operations center URL.
9 Required if using a local folder on the operations center server or an SCM tool as the Configuration as Code bundle location.

Example plugins.yaml file

plugins.yaml for a controller

plugins: # In CloudBees Assurance Program (CAP) - id: "bitbucket-branch-source" - id: "branch-api" - id: "cloudbees-casc-client" - id: "cloudbees-casc-items-api" - id: "cloudbees-casc-items-commons" - id: "cloudbees-casc-items-controller" - id: "cloudbees-template" - id: "cloudbees-workflow-template" - id: "configuration-as-code" - id: "git" - id: "github-branch-source" - id: "infradna-backup" - id: "support-core" - id: "workflow-multibranch" # Not in CAP (see plugin-catalog.yaml) - id: "manage-permission"

plugins.yaml for an operations center

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 plugin-catalog.yaml file

The plugin-catalog.yaml file is only part of a CasC bundle for bundles describing a controller configuration.

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

items.yaml for a controller
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
items.yaml for an operations center
  • If creating a new controller item, refer to Creating a new controller item using CasC for the operations center.

  • By default, shared agent and shared cloud agent items are configured to be taken online. To configure the shared agent or shared cloud agent item to be taken offline, add the takeOnline property to the items.yaml and set it to false. For example: takeOnline: false.

Folders with limited fields
Folders with extended fields
Freestyle job
Cluster operations
Managed controller
Client controller
Shared agent
Shared cloud agent
Backup
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 replication:(1) config: maxReplicas: 5 replicas: 3 targetCPUUtilizationPercentage: 80 terminationGracePeriodSeconds: 1200 #image: cloudbees/mc-foo-image # uncomment to use a non-default image memory: 3072(2) 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: |- --- apiVersion: apps/v1 kind: StatefulSet metadata: labels: my-label: my-value
1 Settings for a managed controller with CloudBees High Availability (HA), with 3 replicas, autoscaling enabled allowing up to 5 replicas, and a CPU threshold of 80% to trigger upscaling. maxReplicas and targetCPUUtilizationPercentage are not required if autoscaling is disabled. Then maxReplicas is set to 0 by default.
2 Some settings, such as controller memory, require the controller to be reprovisioned for the setting to take effect. If the managed controller is running in High Availability (HA) mode, these changes trigger a rolling restart without reprovisioning.
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 Agent for this cluster" name: "shared-cloud-1" description: "Shared Cloud Agent 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".

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