Configuration as Code (CasC) for Controllers

Configuration as Code (CasC) for Controllers is available on the following platforms:

CloudBees CI on traditional platforms 2.222.4.3 (and higher)
CloudBees CI on modern cloud platforms 2.222.4.3 (and higher)
CloudBees Jenkins Platform 2.222.4.3 (and higher)

Introducing Configuration as Code (CasC) for Controllers

Configuration as Code (CasC) for Controllers simplifies the management of a CloudBees Jenkins Platform cluster by capturing the configuration of CloudBees Jenkins Platform controllers in human-readable declarative configuration files which can then be applied to a controller in a reproducible way. By capturing the configuration in files, it can be treated as a first class revision-controlled artifact - versioned and then applied to controllers while being centrally managed from CloudBees Jenkins Platform Operations Center.

The process of using Configuration as Code (CasC) for Controllers involves the following steps:

Create a configuration bundle
- Manually create all YAML files in code editor
  
  or
- Export from an existing controller
Make configuration bundle available for distribution by Operations Center
- Retrieve files from an SCM
  
  or
- Store files on Operations Center manually
Assign a configuration bundle to a controller
- Setting up a client controller using CasC

Understanding configuration bundles

The configuration of a controller is described in a collection of YAML files referred to as a Configuration as Code (CasC) for Controllers bundle. The Operations Center can store many different configuration bundles representing a selection of predefined controllers. Configuration bundles are stored securely on the Operations Center server which manages the secure distribution of the Configuration as Code (CasC) for Controllers bundles to the correct controllers.

Creating a configuration bundle

To create a new bundle configuration, create each of the files listed below. A Configuration as Code (CasC) for Controllers 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 the plugins that should be installed on the controller.
plugin-catalog.yaml - (Optional) This file contains the plugin catalog definitions that should be created on the controller.
items.yaml - (Optional) This file contains the items to be created on the controller. Currently, only folders can be managed and only a subset of fields are supported.
rbac.yaml - (Optional) This file contains all of the role-based access control (RBAC) groups and roles defined at the root level.

For the bundle to be valid, all of the above files must have exactly these 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.

The items.yaml and rbac.yaml files are only available in CloudBees CI release 2.249.3.1+.

bundle.yaml

The bundle.yaml file is an index file that describes the bundle and references the other files in the bundle. The file must contain all of the properties listed below:

Property Type Description

Property	Type	Description
id	string	This bundle’s unique identifier
version	string	This bundle’s version, this value should be incremented whenever the bundle is modified.
apiVersion	String	This is the bundle’s API version. Currently, the expected value is "1".
description	string	A helpful description of this bundle.
plugins	list of strings	This indicates the bundle contains a `plugins.yaml` file.
jcasc	list of strings	This indicates the bundle contains a `jenkins.yaml` file. This item must be included as the `jenkins.yaml` file is required.
items	list of strings	This indicates the bundle contains a `items.yaml` file.
catalog	list of strings	This indicates the bundle contains a `catalog.yaml` file.
rbac	list of strings	This indicates the bundle contains a `rbac.yaml` file.

string

This bundle’s unique identifier

version

string

This bundle’s version, this value should be incremented whenever the bundle is modified.

apiVersion

String

This is the bundle’s API version. Currently, the expected value is "1".

description

string

A helpful description of this bundle.

plugins

list of strings

This indicates the bundle contains a plugins.yaml file.

jcasc

list of strings

This indicates the bundle contains a jenkins.yaml file. This item must be included as the jenkins.yaml file is required.

items

list of strings

This indicates the bundle contains a items.yaml file.

catalog

list of strings

This indicates the bundle contains a catalog.yaml file.

rbac

list of strings

This indicates the bundle contains a rbac.yaml file.

Sample bundle.yaml file

id: "git-bundle"
version: "1"
apiVersion: "1"
description: "A simple bundle that sets up a controller with the git-client plugin"
plugins:
  - "plugins.yaml"
jcasc:
  - "jenkins.yaml"
items:
  - "items.yaml"
catalog:
  - "plugin-catalog.yaml"
rbac:
  - "rbac.yaml"

jenkins.yaml

This file is the main Configuration as Code (CasC) for Controllers configuration file that describes the controller. For more information on how to format this file, see the documentation of the Jenkins Configuration-as-Code plugin.

Sample jenkins.yaml file

jenkins:
  systemMessage: "Jenkins configured using CasC."
  numExecutors: 0
  mode: NORMAL
  securityRealm:
    local:
      allowsSignup: false
      users:
       - id: admin
         password: Qmas9pHXb9wpvp36FaAQ2SBN7XBxsG3h
       - id: newuser
         password: VzHAzoGzHeoq4JF797p8Mb7qL2Ycv54A
  authorizationStrategy: "cloudBeesRoleBasedAccessControl" (1)

1	Mandatory to use CloudBees RBAC configured with CasC. See Configuring RBAC with CasC for more information.

plugins.yaml

This file lists all of the plugins that should be installed on the controller. All plugins listed must be in the CloudBees Assurance Program (CAP). Plugins outside of CAP (for example, Open Source or your own plugins) should be added via a Plugin Catalog (see the next section).

The contents of this file should be a list of plugin IDs. Find many popular plugins and their IDs at the following sites:

Sample plugins.yaml file

plugins:
  - {id: "git"}
  - {id: "maven-plugin"}
  - {id: "configuration-as-code"}
  - {id: "cloudbees-casc-api"}
  - {id: "manage-permission"}
  - {id: "nectar-rbac"}

plugin-catalog.yaml

This file defines the catalog of plugins that are available for installation on the controller. The plugin catalog contains a list of plugins along with the version that should be installed. An optional location can also be specified for plugins that are not available in the standard update centers. For more information on Plugin Catalogs, see Configuring plugin catalogs.

Plugins will not actually be installed on the controller unless they are listed in plugins.yaml. Transitive dependencies are not automatically added. See Calculating plugin dependencies for more information on creating a list of transitive dependencies.

The Plugin Template Catalog feature can be also used separately (non-CasC) on CloudBees Jenkins Platform controllers as described in the documentation. However when using it inside a CasC bundle there are some limitations. See Plugin Catalog limitations in CasC for more information.

Sample plugin-catalog.yaml file

type: "plugin-catalog"
version: "1" (1)
name: "java-catalog"
displayName: "Java Controller Catalog"
configurations:
- description: "java-builder"
  includePlugins:
    artifactory:
      version: 3.3.2
    checkstyle:
      version: 4.0.0
    warnings-ng:
      version: 5.3.0
    my-custom-plugin:
      url: http://www.example.org/jenkins-plugins/my-custom-plugin-1.2.3.hpi
    manage-permission: (2)
      version: X.X (3)

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 X.X with most recent version.

items.yaml

The purpose of the items.yaml file is to describe the items to be created in the controller instance. Currently, only folders can be managed and only a subset of fields are supported. Items present on the instance in the UI but not included in the items.yaml file will remain. The items.yaml file is only available on instances using CloudBees CI version 2.249.3.1 or higher and the CloudBees CasC API plugin and CloudBees Folders plugin.

Property Type Description

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 controller instance as part of the creation process.
rbac	string	Required. The only supported value is SYNC. It specifies the strategy followed to handle an existing configuration when a new configuration is applied. The SYNC value means that groups or roles that are not present in the `rbac.yaml` are removed. If the role or group already exists but the configuration changes then the new configuration is applied.
items	list of objects	Required. The list of items on the controller.
kind	string	Required. Only supported value is “folder”. It defines the kind of item created on the controller.
name	string	Required. The name of the item on the controller.
displayName	string	Optional. The display name of the item on controller.
description	string	Optional. The description of the item on the controller.
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.

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 controller instance as part of the creation process.

rbac

string

Required. The only supported value is SYNC. It specifies the strategy followed to handle an existing configuration when a new configuration is applied. The SYNC value means that groups or roles that are not present in the rbac.yaml are removed. If the role or group already exists but the configuration changes then the new configuration is applied.

items

list of objects

Required. The list of items on the controller.

kind

string

Required. Only supported value is “folder”. It defines the kind of item created on the controller.

name

string

Required. The name of the item on the controller.

displayName

string

Optional. The display name of the item on controller.

description

string

Optional. The description of the item on the controller.

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.

Sample items.yaml file

removeStrategy:
 items: "none"
 rbac: "sync"

items:
 - kind: "folder"
   name: "Acceptance Test Harness"
   displayName: "ATH"
   description: "This contains all the Acceptance Test Harness jobs"
   groups:
     - name: "ATH Administrators"
       members:
         users:
           - "jane-doe"
       roles:
         - name: "administer"
   items:
     - kind: "folder"
       name: "Test A"
       filteredRoles:
         - "developer"
         - "browser"
       items: (1)
         - kind: "folder"
           name: "cjoc-ath"
         - kind: "folder"
           name: "cje-ath"
 - kind: "folder"
   name: "Plugins"

1	Items can be nested within other items, enabling users to create a folder structure on a controller.

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. Currently, only roles and groups on controllers can be managed and only a subset of fields are supported. Roles and groups present on the instance in the UI but not included in the items.yaml file will be removed. The rbac.yaml file is only available on instances using CloudBees CI version 2.249.3.Y or higher, the CloudBees CasC API plugin (must be downloaded manually), and CloudBees Folders plugin (downloaded by default). See Configuring RBAC with CasC for more information.

Property Type Description

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. The only supported value is SYNC. It specifies the strategy followed to handle an existing configuration when a new configuration is applied. The SYNC value means that groups or roles that are not present in the `rbac.yaml` are removed. If the role or group already exists but the configuration changes then the 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.

removeStrategy

object

Required. It specifies the strategy followed to handle an existing configuration when a new configuration is applied.

rbac

string

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.

Sample rbac.yaml file

removeStrategy:
  rbac: "sync"

roles:
- permissions:
  - hudson.model.Hudson.Administer
  name: administer
- filterable: 'true'
  permissions:
  - hudson.model.Hudson.Read
  name: browser
- filterable: 'true'
  permissions:
  - hudson.model.Hudson.Read
  - hudson.model.Item.Configure
  name: developer

groups:
- members:
    users:
    - jane-doe
    internal_groups:
    - "Manager group"
    external_groups:
    - "ldap-developers"
  roles:
  - name: administer
    grantedAt: current
  name: Administrators
- roles: (1)
  - name: developer
    grantedAt: current
  name: Developers
- roles:
  - name: browser
    grantedAt: current
  name: Browsers

1	This is a group without members assigned, so it begins with the roles assigned to the group.

Exporting a CasC bundle

Configuration as Code (CasC) for Controllers includes a method for exporting Configuration as Code (CasC) for Controllers YAML files from pre-existing controllers. This method is helpful for creating example files that can then be used to create a new controller that can be connected to Operations Center with Configuration as Code (CasC) for Controllers. However, the generated bundle should not be used as is and must be updated manually.

The export feature in Configuration as Code (CasC) for Controllers relies on Jenkins LTS - Configuration as Code export, which has limitations (See JCasC Jenkins LTS documentation for more information). In other words, the configuration bundle generated by exporting it from an existing controller is not offering a complete, correct, and ready-to-use configuration bundle.

One reason the exported bundle is incomplete is that some plugins are only partially compatible with Configuration as Code, which means they can read and load the configuration coming from Configuration as Code (CasC) for Controllers; however, they are not generating the correct YAML when exporting. Also, the jenkins.yaml section can include extraneous default values for some properties that can be removed.

When exporting CasC bundles from existing controllers, it is recommended that the controller has no BeeKeeper warnings related to plugins when doing the export, as the exporting logic relies on CloudBees Assurance Program to generate consistent plugins.yaml and plugin-catalog.yaml files. The export will still return content when there are BeeKeeper warnings; however, the consistency of plugins.yaml and plugins-catalog.yaml is not guaranteed. In other words, the files might not be usable without modifications because there will be warning comments in those files pointing to the conflicting plugins.

Prerequisites

The items.yaml and rbac.yaml files are only available in CloudBees CI release 2.249.3.Y+.
Configuration as Code plugin
CloudBees CasC API Plugin, version 1.2 or later

To Export a Configuration as Code (CasC) for Controllers bundle from an existing controller:

Create a test controller in your cluster using the UI.
Configure it (plugins and global configuration) using the UI.
(Optional) Configure a Plugin Catalog using the UI.
From the controller, navigate to Manage Jenkins > CloudBees Configuration as Code bundle.

Export the files by selecting the export icon next to each file listed.

Figure 1. CloudBees Configuration as Code bundle

You can have a configuration bundle without the plugin-catalog.yaml, plugins.yaml, items.yaml, and rbac.yaml files. If you do not include these files in your bundle, they should not be listed in your bundle.yaml file.

If the controller has CloudBees Assurance Program (CAP)/Beekeeper disabled, the files plugins.yaml and plugin-catalog.yaml are included in the list of files, but they contain one of the following warning messages instead of the expected content:

plugin-catalog.yaml message: Cannot export catalog because CAP is not enabled
plugins.yaml message: Cannot export plugins because CAP is not enabled

Save the files using the following file names:
- bundle.yaml
- jenkins.yaml
- plugins.yaml
- plugin-catalog.yaml
- rbac.yaml
- items.yaml
  
  For the bundle to be valid, all of the above files must use these exact filenames.

After creating a configuration bundle based on the export files, add the bundle as a new controller and connect it to Operations Center using a casc-bundle-link.yaml file. See Setting up a client controller using CasC for more information.

You must remove the obsolete connection details, operationsCenterRootAction, from the jenkins.yaml file before connecting it to the Operations Center so new connection details can be established for this new controller. Connection details are specific for a controller, and cannot be shared between controllers. If you release a client controller the connection details also change. Do not include them unless you really know what you are doing. If operationsCenterRootAction is not present the in the jenkins.yaml file, Operations Center will create it in the background.

The original test controller created in the UI can be deleted as it is no longer needed.

Example exported bundle files

bundle.yaml

id: "0-client-controller"
description: "Autogenerated bundle descriptor"
version: "1"
apiVersion: "1"
plugins:
  - "plugins.yaml"
jcasc:
  - "jenkins.yaml"
catalog:
  - "plugin-catalog.yaml"

jenkins.yaml

jenkins:
  agentProtocols:
  - "Diagnostic-Ping"
  - "JNLP4-connect"
  - "OperationsCenter2"
  - "Ping"
  authorizationStrategy: "cloudBeesRoleBasedAccessControl"
  disableRememberMe: false
  markupFormatter: "plainText"
  mode: NORMAL
  myViewsTabBar: "standard"
  numExecutors: 0
  primaryView:
    all:
      name: "all"
  projectNamingStrategy: "standard"
  quietPeriod: 5
  remotingSecurity:
    enabled: false
  scmCheckoutRetryCount: 0
  systemMessage: |+
    v3 - Controller configured automatically by CasC from Operations Center

  updateCenter:
    sites:
    - id: "virtual-cap-core-cm"
      url: "https://jenkins-updates.cloudbees.com/update-center/envelope-core-cm/update-center.json"
  views:
  - all:
      name: "all"
  viewsTabBar: "standard"
security:
  apiToken:
    creationOfLegacyTokenEnabled: false
    tokenGenerationOnCreationEnabled: false
    usageStatisticsEnabled: true
  sSHD:
    port: -1
unclassified:
  contentFilters:
    enabled: false
  experimentalPlugins:
    enabled: false
  location:
    adminAddress: "address not configured yet <nobody@nowhere>"
    url: "http://127.0.0.1.beesdns.com:8080/"
  mailer:
    charset: "UTF-8"
    useSsl: false
  operationsCenterRootAction:
    connectionDetails: "----- BEGIN CONNECTION DETAILS -----\nH4sIAAAAAAAAAA3KQQ6DIBBA0bvMugNDkeBwG8TRmihtYLpqenfJ3738H+wtV4UEW8jBcWD0PjJO\r\
      \nvBEumQllKsHNJc7REzzgWMdLWM5DquKVu0ob/G3n8JfqJ1nrntHQyJlFpK+1m/K+EhOThf8NZy3p\r\
      \n8XIAAAA=\r\n----- END CONNECTION DETAILS -----\n"
  pollSCM:
    pollingThreadCount: 10

plugins.yaml

plugins:
- {id: "trilead-api"}
- {id: "configuration-as-code"}
- {id: "mapdb-api"}
- {id: "junit"}
- {id: "cloudbees-folder"}
- {id: "display-url-api"}
- {id: "cloudbees-uc-data-api"}
- {id: "operations-center-client"}
- {id: "cloudbees-analytics"}
- {id: "command-launcher"}
- {id: "metrics"}
- {id: "mailer"}
- {id: "nectar-rbac"}
- {id: "operations-center-context"}
- {id: "async-http-client"}
- {id: "script-security"}
- {id: "cloudbees-folders-plus"}
- {id: "variant"}
- {id: "blueocean-commons"}
- {id: "jaxb"}
- {id: "jdk-tool"}
- {id: "cloudbees-license"}
- {id: "structs"}
- {id: "support-core"}
- {id: "scm-api"}
- {id: "token-macro"}
- {id: "nectar-license"}
- {id: "operations-center-agent"}
- {id: "cloudbees-administrative-monitors"}
- {id: "cloudbees-assurance"}
- {id: "credentials"}
- {id: "workflow-api"}
- {id: "jackson2-api"}
- {id: "cloudbees-blueocean-default-theme"}
- {id: "workflow-step-api"}
- {id: "bouncycastle-api"}
- {id: "apache-httpcomponents-client-4-api"}
- {id: "javadoc"}
- {id: "ldap"}
- {id: "pam-auth"}
- {id: "matrix-auth"}
- {id: "antisamy-markup-formatter"}
- {id: "matrix-project"}

plugin-catalog.yaml

type: "plugin-catalog"
version: "1"
name: "cloudbees-assurance-program-extensions"
displayName: "Extensions to the CloudBees Assurance Program (CAP)"
configurations:
- description: "Extensions to the CAP"
  includePlugins:
    pipeline-maven: {version: 3.8.1}
    sonar: {version: '2.11'}
    cloudbees-request-filter: {version: '1.5'}
    manage-permission: {version: '1.0'}
    h2-api: {version: 1.4.199}
    cloudbees-cloudfoundry-cli: {version: 2.1.6}
    operations-center-client: {version: 2.249.0.11}
    nectar-rbac: {version: '5.46'}

items.yaml

removeStrategy:
  rbac: SYNC
  items: NONE
items:
- kind: folder
  name: Acceptance Tests
  description: This contains all the Acceptance Test jobs
  groups:
  - members:
      users:
      - ada-lovelace
    roles:
    - name: administer
      grantedAt: current
    name: ATH Administrators
  items:
  - kind: folder
    name: Quick Tests
  - kind: folder
    name: Slow Tests

rbac.yaml

removeStrategy:
  rbac: SYNC
roles:
- permissions:
  - hudson.model.Hudson.Administer
  name: administer
- filterable: 'true'
  permissions:
  - hudson.model.Hudson.Read
  name: browser
- filterable: 'true'
  permissions:
  - hudson.model.Hudson.Read
  - hudson.model.Item.Configure
  name: developer
groups:
- members:
    users:
    - jane-doe
  roles:
  - name: administer
    grantedAt: current
  name: Administrators
- roles:
  - name: developer
    grantedAt: current
  name: Developers
- roles:
  - name: browser
    grantedAt: current
  name: Browsers

Adding a CasC bundle to Operations Center

Configuration bundles are made available from the Operations Center to connected controllers using HTTP/HTTPS. Configuration bundles are stored on the Operations Center server as a directory containing the bundle files. Multiple Configuration as Code (CasC) for Controllers bundles can be deployed to the Operations Center server and are all stored in $JENKINS_HOME/jcasc-bundles-store.

Example directory for multiple CasC bundles

$JENKINS_HOME/jcasc-bundles-store/
├── bundle-1
│   ├── bundle.yaml
│   ├── jenkins.yaml
│   ├── plugin-catalog.yaml
│   └── plugins.yaml
└── bundle-2
    ├── bundle.yaml
    ├── jenkins.yaml
    ├── plugin-catalog.yaml
    └── plugins.yaml

To deploy a Configuration as Code (CasC) for Controllers bundle to the Operations Center, copy the directory containing the bundle files to your $JENKINS_HOME/jcasc-bundles-store directory. Ensure the owner and group of the bundle directory and files match those of other files under $JENKINS_HOME and are sufficient to allow the Jenkins user to read the files.

Loading CasC bundles from a SCM tool

Operations Center distributes Configuration as Code (CasC) for Controllers bundles to controllers from local storage; however, Configuration as Code (CasC) for Controllers bundles can also be pulled from an external source control management (SCM) system using a Freestyle job in Operations Center that can be triggered manually or using a webhook.

Prerequisites

Configuration as Code (CasC) for Controllers bundles can be in one or more SCM repositories; however, this guide assumes all bundles are in the same Git repository, with the following layout:

mycompany.com/config-bundles.git
- my-controller-1
  -- bundle.yaml
  -- jenkins.yaml
  -- plugins.yaml
  -- plugin-catalog.yaml
- my-controller-2
  -- bundle.yaml
  …

Creating a job in Operations Center

Operations Center distributes bundles from local storage, so to use files from an external SCM system you must create a Freestyle job to pull those bundles from the SCM to local storage.

To create a job to pull Configuration as Code (CasC) for Controllers bundles from an SCM to local storage:

Create a Freestyle job in Operations Center.

You must use a Freestyle job as Pipeline jobs are not supported in Operations Center.
In the Source Code Management section, select an SCM that is supported by Jenkins and enter the repository location.
In the Build section, add an Execute Shell step with the following script:
```
cp -r my-master-1 $JENKINS_HOME/jcasc-bundles-store
cp -r my-master-2 $JENKINS_HOME/jcasc-bundles-store
```
$JENKINS_HOME/ is the default Jenkins home directory in CloudBees CI. Update the script if your Jenkins home directory is in a different location.
Save and trigger a build.

Afterwards, Configuration as Code (CasC) for Controllers bundles should be available in local storage and ready to be used by controllers following the normal procedure.

Triggering the job automatically using Webhooks

One way to trigger a Freestyle job to pull Configuration as Code (CasC) for Controllers bundles from an SCM is through the use of webhooks. If your SCM supports Webhooks, configure a webhook in the SCM to trigger builds on the importing job on push events.

Setting up a webhook through your SCM will ensure a change made in the repository will be automatically available to controllers using the Configuration as Code (CasC) for Controllers bundle.

Updating a CasC bundle

A configuration bundle can be updated on the Operations Center and will then be automatically distributed to the controllers that were initialized with that bundle.

After the initial configuration on startup, there is a background process in the controller which is checking for updates of the configuration bundle on Operations Center. If there is an update, then the update process shows an Administrative Monitor in the controller to inform the user about the new available configuration.

You can also check for updates on the CloudBees Configuration as Code bundle page on the Bundle Update tab. A new alert will appear underneath the CloudBees Configuration as Code bundle icon on the controller Manage Jenkins page.

This option is available to users with the Overall/Manage permission, allowing users to delegate the task away from the Administrator role. See Delegating Administration for more information.

To check for updates in the UI:

Navigate to the controller.
Select Manage Jenkins in the left pane.
Select CloudBees Configuration as Code bundle.
Select the Bundle Update tab.

A blue bell will appear next to the tab title if a new update has been detected.
Select Check for Updates.
If bundle updates are available, select one of the following options:
- Safe Restart - Restarts the controller with the new configuration applied.
- Reload Configuration - Applies the new configuration without a restart. This is called a hot reload. See Using hot reload on a configuration bundle for more information on when hot reload is appropriate.

A bundle update will only be detected when the version attribute specified in the bundle.yaml file has been updated. If the version attribute is not incremented then connected controllers will not get the updates in the bundle.

When a controller finds an update to its configuration bundle, an alert is displayed in the Manage Jenkins area.

Apply the update when the controller must be restarted; select an appropriate time to do this and then select Safe Restart to have the controller restart and apply the updated configuration bundle.

In some instances, a restart will not be required to apply an update to the controller. See Using hot reload on a configuration bundle for more information.

By default controllers will check for updates every twenty minutes, but this can be customized by setting the Java system property com.cloudbees.opscenter.client.casc.ConfigurationUpdaterTask.recurrencePeriod to the desired interval, in minutes. For example, to have a client controller check for updates every five minutes, use the following startup command:

java -Dcore.casc.config.bundle=$JENKINS_HOME/casc-bundle-link.yaml \
 -Dcom.cloudbees.opscenter.client.casc.ConfigurationUpdaterTask.recurrencePeriod=5 \
 -jar jenkins.war

Understanding risks related to updating CasC files

Managing your controllers with CasC gives you great power and flexibility. With this power and flexibility come risks for errors that could impact your installation. Please review the information below to help guide you as you evolve your CasC bundle.

Risks when updating the `bundle.yaml` file

The version attribute of this file needs to be updated (incremented) when something changes in the bundle (in any other file). Other attributes rarely change (they are just pointing to the other files in the bundle).

If the version attribute is not incremented then connected controllers will not get the changes in the bundle.

Risks when updating the `plugins.yaml` file

CloudBees Assurance Program (CAP) Tier 1 plugins can be added to your controller by adding the plugins to this file. Deleting plugins from the file will not remove them from the controller. To remove plugins from the controller, delete them in the UI, and before restarting the controller, delete them from the plugins.yaml file or they will be reinstalled.

There are no "delete/uninstall” operations when using CasC in general.

All plugins in this file must be CloudBees Assurance Program (CAP) Tier 1 plugins.

To get the list of CloudBees Tier 1 plugins:

Navigate to CloudBees CI Plugins.
To verify that your plugin is a CloudBees Tier 1 plugin, you can either:
- Search for a specific plugin and filter based on Verified or Proprietary (Tier 1).
- Scroll to the bottom of the page and select All Tier 1 plugins to browse all Tier 1 plugins.

For more information on the CloudBees Assurance Program and how CloudBees classifies plugins see CloudBees plugin support policies.

If you want to add a plugin to your controller that is not in CAP as Tier 1, add the plugin to the plugin-catalog.yaml file.

When adding a plugin to the plugin-catalog.yaml file which is not a CloudBees Assurance Program (CAP) Tier 1 plugin, all of its dependencies also need to be included either in the plugin-catalog.yaml file or this file if they are Tier 1 in CAP. If the dependencies are not in either file, then the plugin will not be installed and their absence could potentially cause other issues, for example configuration from jenkins.yaml not applicable thus a start up error.

Risks when updating the `plugin-catalog.yaml` file

If you want to add a plugin to your controller that is not in CloudBees Assurance Program (CAP) as Tier 1, add the plugin to the this file. You will also need to add the plugin’s dependencies either to this file or the plugins.yaml file if they are in CAP as Tier 1.

The plugins in the this file need to be compatible with the set of CAP Tier 1 plugins in the plugins.yaml file. A validation of the plugin-catalog.yaml file is run at startup time.

If this validation fails, the plugins in the`plugin-catalog.yaml` file are not installed and your controller will continue with its normal startup. This scenario means plugins are not installed, which might lead to other issues, for example specific configurations in jenkins.yaml cannot be applied.

Risks when updating the `jenkins.yaml` file

This file is edited to change or add Jenkins configurations. There is a wide variety of possible combinations (depending on the plugins being configured as code). This file is entirely managed by the Jenkins LTS - Configuration as Code (JCasC) plugin. In other words, all Jenkins LTS documentation, reported bugs, community blogs, Gitter chats, etc. apply to this file.

The bulk of the content in this file is defined by the various plugins you have installed with only a small portion of it defined by the Jenkins core itself. However, there are a few general items to consider when editing the file:

Removing configurations from this file does not remove the configuration from an existing controller.
Adding configurations requires the underlying plugin that the configuration references to be installed. Jenkins startup will fail otherwise.
Backward compatibility depends on the specific plugins being configured. If a plugin changes its configuration in an incompatible way, then the controller will fail to start (until the jenkins.yaml file is adapted, or the section in that file related to the plugin removed).
This file may contain data which is tied to a specific CloudBees instance, such as encoded secrets, Operations Center connection details, and others, so a jenkins.yaml is, in general, suitable for a single CloudBees controller instance. This might lead to indecipherable secrets, controller to Operations Center connection failing, and many more things depending on the specific configuration.

Using hot reload on a configuration bundle

Configuration as Code (CasC) for Controllers allows users to reload a configuration file without restarting the instance. Since the Configuration as Code (CasC) for Controllers plugin manages plugin updates and the Plugin Catalog, validating a hot reload is a more complex process. A bundle reload is not always possible. If there are plugin upgrades in the incoming bundle, then Jenkins needs to be restarted.

If the reload is possible, then the following operations are automatically performed:

Update the Plugin Catalog
Install any new plugins
Call the API on configuration-as-code to reload the Jenkins configuration

Configuration bundles that do not include plugin update requirements can be reloaded without an instance restart. This feature allows users to update Jenkins configurations, install new Plugin Catalogs, or install new plugins dynamically.

Setting up a client controller using CasC

Controller send requests for their bundles through a secure HTTP(S) endpoint in Operations Center. Each controller is aware of the bundle it is connected to through the casc-bundle-link.yaml file that contains the bundle URL and access token.

You can configure a client controller using Configuration as Code (CasC) for Controllers by providing it with the location of the appropriate bundle and access token contained in the casc-bundle-link.yaml file. The client controller fetches its configuration bundle using the details in the casc-bundle-link.yaml file and configures itself accordingly.

The process of setting up a client controller involves the following steps:

Downloading the casc-bundle-link.yaml file
Configuring client controllers with the casc-bundle-link.yaml file

Downloading the `casc-bundle-link.yaml` file

The connection details needed in the casc-bundle-link.yaml file, the bundle URL and the access token, are available in Operations Center.

To download the casc-bundle-link.yaml file:

Ensure you are logged in to Operations Center as a user with the Administer permission.
From the Operations Center dashboard, select Manage Jenkins in the left pane.
Select Configuration as Code Bundles.
Find the configuration bundle in the list.
To download the casc-bundle-link.yaml file, select the Download link file icon for the appropriate configuration bundle.
Save the file anywhere in the controller’s filesystem.

CloudBees recommends saving the casc-bundle-link.yaml file in the controller’s $JENKINS_HOME directory.

The casc-bundle-link.yaml file contains the following properties:

Property	Type	Description
url	String	The URL where the bundle can be fetched. This URL references both the Operations Center server and the id of the bundle.
token	String	The access token to authenticate the request with the Operations Center server.

Property

Type

Description

url

String

The URL where the bundle can be fetched. This URL references both the Operations Center server and the id of the bundle.

token

String

The access token to authenticate the request with the Operations Center server.

The URL to access a particular bundle from an Operations Center server has a well-defined format: \http[s]://<oc-server>:<port>/config-bundle/<bundle directory> For example, given an Operations Center server on host oc1.example.org and port 8080 the bundle that was placed in directory bundle-1 would be accessed as: https://oc1.example.org:8080/config-bundle/bundle-1.

Configuring client controllers with the `casc-bundle-link.yaml` file

The client controller is directed to use the casc-bundle-link.yaml file by setting a Java system property. On startup, the client controller reads the casc-bundle-link.yaml file, fetches its Configuration as Code (CasC) for Controllers bundle from the Operations Center using the details specified in the casc-bundle-link.yaml file, then initializes itself with the provided configuration.

To point the client controller at the casc-bundle-link.yaml file, set the Java system property core.casc.config.bundle to the location of the link file. For example, to start a client controller using the casc-bundle-link.yaml file at $JENKINS_HOME/casc-bundle-link.yaml use the following command: java -Dcore.casc.config.bundle=$JENKINS_HOME/casc-bundle-link.yaml -jar jenkins.war

After you start the client controller with the correct java system property, open Operations Center and connect the client controller in the UI.

If there are any errors processing the casc-bundle-link.yaml file, fetching the bundle from the Operations Center, or initializing based on the bundle, these will be displayed on the console.

Viewing bundles in Operations Center

To view all available bundles:

Ensure you are logged in to Operations Center as a user with the Administer permission.
From the Operations Center dashboard, select Manage Jenkins in the left pane.
Select Configuration as Code Bundles.

For each bundle, the following attributes are displayed:

Bundle name: The bundle name. It matches the name of the directory containing the bundle in the filesystem.
URL: The bundle URL where Operations Center exposes its content.

Availability pattern: The full path to one or more controllers in Operations Center that can use the bundle. This must be a regular expression and defines the bundles you can assign to a controller from the controller configuration screen. For more information, see Assigning a bundle to a controller.

The Availability pattern supports the Java implementation of regular expression pattern matching.
If the Availability pattern checkbox is selected, and the Availability pattern field is empty, the bundle can be used by any controller. This option provides more flexibility, but is less secure.

Token: The access token for the bundle.
Actions: The three actions available for each bundle.
- Regenerate the security token: Regenerates the security token. For more information, see Re-generating a bundle token.
- Copy link file content: Copies the content of the casc-bundle-link.yaml file to the clipboard. As described in other sections, the casc-bundle-link.yaml file is a YAML formatted file containing the URL and the token to access the bundle in Operations Center.
- Download link file: Downloads the casc-bundle-link.yaml file. For more information, see Downloading the casc-bundle-link.yaml file.

Assigning a bundle to a controller

Assigning a bundle to more than one controller is a Preview feature.

Preview

A Preview feature:

Has not undergone end-to-end testing with CloudBees products
Is provided without service-level agreements (SLA) and therefore does not include CloudBees' commitment on functionality or performance
May impact other stable areas of the product when used
May have limited documentation
May not be feature complete during the Preview period
May graduate from preview state to fully supported or be removed from the product
May introduce incompatible, backward-breaking changes that could revoke the ability to upgrade

Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

Ensure you are logged in to Operations Center as a user with the Administer permission.
From the Operations Center dashboard, select Manage Jenkins in the left pane.
Select Configuration as Code Bundles.

Define the Availability pattern for the controller. You have two options:

Option 1: In the Availability pattern field, define the path to the controllers that can use the bundle and select Save. This must be a regular expression and specifies the bundles you can assign to a controller from the controller configuration screen. The Availability pattern supports the Java implementation of regular expression pattern matching.

Table 1. Availability pattern examples
Example scenario	Example Availability pattern
A controller with the name "casc-controller" created directly in the root of Operations Center.	`casc-controller`
A controller with the name "casc-controller" created inside the "folder1" folder.	`folder1/casc-controller`
Two controllers with the name "casc-controller-1" and "casc-controller-2", created directly in the root of Operations Center.	`casc-controller-\d`
Any controller.	`.*`
Any controller in the "folder1" folder.	`folder1/.*`

Option 2: Leave the Availability pattern field empty. Under Settings, select the Availability pattern checkbox and select Save. When the Availability pattern field is empty, the bundle can be used by any controller. This option provides more flexibility, but is less secure.

Select Dashboard to navigate to the Operations Center dashboard.
Select the down arrow to the right of your controller (avoiding its name) and select Configure from the dropdown menu.

Figure 2. Controller dropdown menu
Scroll down to Configuration as Code (CasC).
Select the appropriate bundle to assign to the controller.
Select Save.
If the controller has already been provisioned, you must re-provision it for the configuration change to take effect.

Re-generating a bundle token

This action re-generates the access token for a bundle. Regenerating the access token is not usually required and should only be done in certain situations, such as for security purposes. Any controller currently using the token will lose access to it after it is re-generated.

If the token needs to be re-generated, then the controller using the token needs to be properly reconfigured. The casc-bundle-link.yaml file needs to be updated with the new token. For more information, see Configuring client controllers with the casc-bundle-link.yaml file.

Creating folders with CasC

Configuration as Code (CasC) for Controllers allows users to create folders if the “items.yaml” file is included with the configuration bundle. Currently, only folders can be managed and only a subset of fields are supported.

Prerequisites

CloudBees CI version 2.249.3.1
Configuration as Code plugin
Folders plugin
CloudBees CasC API Plugin, version 1.2 or later
CloudBees Role-Based Access Control Plugin (Optional)

Exporting folder configurations

Users can export folder configurations from an existing controller. See Exporting a CasC bundle for more information.

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 folders

bundle.yaml

apiVersion: "1"
id: "1-casc-with-folders"
description: "Bundle demo with folders"
version: "1"
plugins:
  - "plugins.yaml"
jcasc:
  - "jenkins.yaml"
catalog:
  - "plugin-catalog.yaml"
rbac:
  - "rbac.yaml"
items:
  - "items.yaml"

plugins.yaml

plugins:
- {id: configuration-as-code}
- {id: cloudbees-casc-api}
- {id: manage-permission}
- {id: nectar-rbac}

plugin-catalog.yaml

type: "plugin-catalog"
version: "1"
name: "cloudbees-assurance-program-extensions"
displayName: "Extensions to the CloudBees Assurance Program (CAP)"
configurations:
- description: "Extensions to the CAP"
  includePlugins:
    manage-permission: (1)
      version: X.X (2)

1	Add the manage-permission plugin to enable the `Overall.MANAGE` permission.
2	Replace X.X with most recent version.

jenkins.yaml

jenkins:
  systemMessage: "Configured automatically by Configuration as Code - with RBAC \n\n"
  authorizationStrategy: "cloudBeesRoleBasedAccessControl" (1)

1	Mandatory to use CloudBees RBAC configured with CasC.

rbac.yaml

removeStrategy:
  rbac: "SYNC" (1)

groups:
- name: "Administrators group"
  members:
    users:
    - "admin-user"
  roles:
  - name: "administer-role"
    grantedAt: "current" (2)
    propagates: "false"
- name: "Manager group"
  members:
    users:
    - "manager-user"
  roles: (3)
  - name: "manager-role"
    grantedAt: "current"
- name: "Developers group"
  members:
    users:
    - "dev-user"
    internal_groups: (4)
    - "Manager group"
    external_groups:
    - "ldap-developers"
  roles: (5)
  - name: "developer-role"
    grantedAt: "child"
- name: "Browsers"
  members:
    users:
    - "read-user"
    internal_groups:
    - "Administrators group"
    - "Manager group"
    - "Developers group"
  roles: (6) (7)
- name: "browser-role"

roles:
- name: "administer-role"
  filterable: "false"
  permissions:
  - hudson.model.Hudson.Administer
- name: "manager-role"
  filterable: "false"
  permissions:
  - hudson.model.Hudson.Manage
  - hudson.model.Hudson.Read
- name: "developer-role"
  filterable: "true"
  permissions: (8)
  - hudson.model.Hudson.Read
  - hudson.model.View.Delete
  - hudson.model.Item.Promote
  - hudson.model.View.Configure
  - hudson.model.Item.Configure
  - hudson.model.Item.Cancel
  - hudson.model.Item.Read
  - hudson.model.Item.Build
  - hudson.model.Item.Discover
  - hudson.model.Hudson.Read
  - hudson.model.Item.Create
  - hudson.model.View.Read
  - hudson.model.View.Create
  - hudson.model.Item.Delete
- name: "browser-role"
  filterable: "true"
  permissions:
  - hudson.model.Hudson.Read
- name: "authenticated” (9)
  filterable: "false"
  permissions:
  - hudson.model.Hudson.Read
- name: "anonymous” (10)
  filterable: "false"

1	For security reasons, SYNC is here to remove groups/roles from CloudBees Continuous Integration when they are removed from this file.
2	Other options that could be used here include: "child" or "grandchild".
3	If propagates is not included, the default value is "true".
4	Team managers are also members of the developer group.
5	If propagates is not included, the default value is "true".
6	If grantedAt is not included, the default value is "current".
7	If propagates is not included, the default value is "true".
8	The list of permissions (Permission.id) to grant this role.
9	Overriding RBAC embedded role to lower the permissions.
10	If there isn’t list of permissions included, the role has no permissions.

items.yaml

removeStrategy:
 items: "none"
 rbac: "sync"

items:
 - kind: "folder"
   name: "Acceptance Test Harness"
   description: "This contains all the Acceptance Test Harness jobs"
   groups:
     - name: "Administrators group"
       members:
         users:
           - "admin-user"
       roles:
         - name: "administer-role"
           grantedAt: "current"
           propagates: "false"
   items:
     - kind: "folder"
       name: "With test-a"
       groups:
         - name: "Test A Administrators"
           members:
             users:
               - "admin-user"
           roles:
             - name: "administer-role"
       items: (1)
         - kind: "folder"
           name: "product-a-ath"
         - kind: "folder"
           name: "product-b-ath"

1	Items can be nested within other items, enabling users to create a folder structure on a controller.

Configuring RBAC with CasC

Configuring role-based access control (RBAC) with Configuration as Code (CasC) for Controllers requires the addition of the rbac.yaml file to the configuration bundle. Additionally, the authorizationStrategy attribute must be added to the jenkins.yaml file.

Prerequisites

CloudBees CI version 2.249.3.1+
Configuration as Code plugin
CloudBees Role-Based Access Control Plugin
CloudBees CasC API Plugin, version 1.2 or later

Required setup

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.

To enable a controller to opt-out of inheriting the Operations Center authorization strategy you must complete the following steps:

On Operations Center, select the Allow client controllers to opt-out checkbox under Client controller security on the Configure Global Security page in Manage Jenkins. See Configuring SSO in Operations Center for information on how to customize security enforcement on controllers.

Select either Enforce Authentication only or Opt out of all security enforcement under Security Setting Enforcement on the Configure page. See Configuring options for individual controllers for information on how to customize the authorization strategy for an individual controller.

You can leave the default Use global security enforcement setting selected if:

Groups and roles are defined in the Operations Center and you do not need to define groups and roles at the controller level using the rbac.yaml file.
RBAC is used with only an items.yaml file.

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.
Folder management: To apply RBAC groups and/or roles to folders, the CasC configuration bundle must include an items.yaml file with the folder items. See Creating folders with CasC for more information.

Exporting RBAC configurations

Users can export role-based access control (RBAC) configurations from an existing controller. See Exporting a CasC bundle for more information.

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 RBAC

For this example, we will create four groups:

Administer: Full permissions on the controller.
Manager: Can manage the controller with the Overall.MANAGE permission.
Developer: Can create pipelines/jobs and use them.
Browser: Read only users.

bundle.yaml

apiVersion: "1"
id: "0-casc-with-rbac"
description: "Bundle demo with rbac"
version: "1"
plugins:
  - "plugins.yaml"
jcasc:
  - "jenkins.yaml"
catalog:
  - "plugin-catalog.yaml"
rbac:
  - "rbac.yaml"

plugins.yaml

plugins:
- {id: configuration-as-code}
- {id: cloudbees-casc-api}
- {id: manage-permission}
- {id: nectar-rbac}

plugin-catalog.yaml

type: "plugin-catalog"
version: "1"
name: "cloudbees-assurance-program-extensions"
displayName: "Extensions to the CloudBees Assurance Program (CAP)"
configurations:
- description: "Extensions to the CAP"
  includePlugins:
    manage-permission: {version: X.X} (1) (2)

1	Add the manage-permission plugin to enable the `Overall.MANAGE` permission. This plugin is not required to configure RBAC with CasC.
2	Replace X.X with most recent version.

jenkins.yaml

jenkins:
  systemMessage: "Configured automatically by Configuration as Code - with RBAC \n\n"
  authorizationStrategy: "cloudBeesRoleBasedAccessControl" (1)

1	Mandatory to use CloudBees RBAC configured with CasC.

rbac.yaml

removeStrategy:
  rbac: "SYNC" (1)
groups:
- name: Administrators
  members:
    users:
    - admin-user
  roles:
  - name: administer-role
    grantedAt: current (2)
    propagates: 'false'
- name: Managers
  members:
    users:
    - manager-user
  roles: (3)
  - name: manager-role
    grantedAt: current
- name: Developers
  members:
    users:
    - dev-user
    internal_groups: (4)
    - managers
    external_groups:
    - ldap-developers
  roles: (5)
  - name: developer-role
    grantedAt: child
- name: Browsers
  members:
    users:
    - read-user
    internal_groups:
    - Administrators
    - Managers
    - Developers
  roles: (6) (7)
  - name: browser-role
roles:
- name: administer-role
  filterable: 'false'
  permissions:
  - hudson.model.Hudson.Administer
- name: manager-role
  filterable: 'false'
  permissions:
  - hudson.model.Hudson.Manage
  - hudson.model.Hudson.Read
- name: developer-role
  filterable: 'true'
  permissions: (8)
  - hudson.model.Hudson.Read
  - hudson.model.View.Delete
  - hudson.model.Item.Promote
  - hudson.model.View.Configure
  - hudson.model.Item.Configure
  - hudson.model.Item.Cancel
  - hudson.model.Item.Read
  - hudson.model.Item.Build
  - hudson.model.Item.Discover
  - hudson.model.Hudson.Read
  - hudson.model.Item.Create
  - hudson.model.View.Read
  - hudson.model.View.Create
  - hudson.model.Item.Delete
- name: browser-role
  filterable: 'true'
  permissions:
  - hudson.model.Hudson.Read
- name: authenticated (9)
  filterable: false
  permissions:
  - hudson.model.Hudson.Read
- name: anonymous (10)
  filterable: 'false'

1	For security reasons, SYNC is here to remove groups/roles from CloudBees Continuous Integration when they are removed from this file.
2	Other options that could be used here include: "child" or "grandchild".
3	If propagates is not included, the default value is "true".
4	Team managers are also members of the developer group.
5	If propagates is not included, the default value is "true".
6	If grantedAt is not included, the default value is "current".
7	If propagates is not included, the default value is "true".
8	The list of permissions (Permission.id) to grant this role.
9	Overriding RBAC embedded role to lower the permissions.
10	Overriding RBAC embedded role to lower the permissions. If there isn’t list of permissions included, the role has no permissions.

Determining plugin compatibility

All CloudBees Assurance Program (CAP) Tier 1 and Tier 2 plugins are compatible with Configuration as Code (CasC) for Controllers at this time; however, they are not all configurable. See Tier 1 and Tier 2 plugins support for Configuration as Code for a list of configurable plugins.

For more information on the CloudBees Assurance Program (CAP) and how CloudBees classifies plugins see CloudBees plugin support policies.

Plugin Catalog limitations in CasC

Plugin Catalogs can be used in Configuration as Code (CasC) for Controllers bundles through the plugin-catalog.yaml file inside the bundle.

The Plugin Catalog feature can be also used separately (non CasC) on CloudBees Jenkins Platform controllers as described in the documentation. However when using it inside a Configuration as Code (CasC) for Controllers bundle there are the following limitations:

Credentials: The use of Jenkins credentials (under the httpCredentialsProvider section) requires a running Jenkins instance; however, Configuration as Code (CasC) for Controllers is designed to run during Jenkins start up, so Jenkins credentials are not available.
Maven 2 layout: This layout is not supported when using Plugin Catalogs in a Configuration as Code (CasC) for Controllers bundle.

Advanced topics

Enabling HTTPS

The security token and Configuration as Code (CasC) for Controllers bundle both contain sensitive information, so it is recommended that they are protected by using HTTPS when sent between the Operations Center and controller. HTTPS must be enabled on the Operations Center side. Typically enabling HTTPS is done by terminating the secure connection externally in a reverse proxy, but it can also be terminated in the Jenkins server. To enable HTTPS, add startup parameters to specify the HTTPS port, server certificate, and key.

Example startup parameters

java -jar jenkins.war --httpsPort=8443 \
--httpsCertificate=/etc/certs/jenkins-cert.cert \
--httpsPrivateKey=/etc/certs/jenkins-cert.key

Using a self-signed certificate

This configuration is not recommended and should not be used in production.

If you are using this method in a limited scope for test deployments, see “Set-up SSL on a CJP environment with a self-sign SSL certificate on each Jenkins box”, a CloudBees Knowledge Base article, for guidance on setting up CloudBees CI with self-signed certificates.

Calculating plugin dependencies

The Plugin Installation Manager Tool can be used to assist with determining the full list of a plugin’s transitive dependencies. The tool takes as input a plugins.yaml that lists plugins you would like to install and outputs a list of all the plugins to be installed, along with all their transitive dependencies. This list can then be used to populate the plugin catalog so the plugins specified in plugins.yaml can be successfully installed.

The plugins.yaml file used by the tool is not the same as the one created previously when authoring the Configuration as Code (CasC) for Controllers bundle.

Prerequisites

The plugin.yaml file from the Configuration as Code (CasC) for Controllers bundle
Java Developer Kit (JDK) installed and configured
Apache Maven installed and configured
(optionally) git installed and configured
Access to the jenkins.war file that will be used to create the connected controller

To create a list of plugins to be installed including all transitive dependencies:

Clone (or download) the Plugin Installation Manager Tool’s repository from https://github.com/jenkinsci/plugin-installation-manager-tool.

Build the tool using the following commands:

cd plugin-installation-manager-tool
mvn clean package

Using the plugins.yaml file from the Configuration as Code (CasC) for Controllers bundle, create a plugins.yaml file for use with the tool. Rename the Configuration as Code (CasC) for Controllers bundle’s plugins.yaml file’s YAML property id to artifactId as illustrated below:

plugins.yaml from Configuration as Code (CasC) for Controllers bundle plugins.yaml for use with tool

`plugins.yaml` from Configuration as Code (CasC) for Controllers bundle	`plugins.yaml` for use with tool
`plugins: - id: "git" - id: "maven-plugin"`	`plugins: - artifactId: "git" - artifactId: "maven-plugin"`

plugins:
  - id: "git"
  - id: "maven-plugin"

plugins:
  - artifactId: "git"
  - artifactId: "maven-plugin"

Run the tool, using the following command, updating it with the location of your controller .war file and the location of your plugins.yaml file:

cd plugin-installation-manager-tool
java -jar \
plugin-management-cli/target/jenkins-plugin-manager-*.jar \
--no-download --plugin-download-directory plugin-download \
--list \
--war $JENKINS_HOME/cloudbees-core-cm.war \  // (1)
--plugin-file plugins.yaml // (2)

1	location of controller `.war` file
2	location of `plugins.yaml` file

Sample output file with list of plugins

File containing list of plugins to be downloaded: plugins.yaml
Reading in plugins from plugins.yaml

Plugin download location: plugin-download
No CLI option or environment variable set for update center, using default of https://updates.jenkins.io
No CLI option or environment variable set for experimental update center, using default of https://updates.jenkins.io/experimental
No CLI option or environment variable set for incrementals mirror, using default of https://repo.jenkins-ci.org/incrementals
Will use war file: $JENKINS_HOME/jenkins.war

Installed plugins:

Bundled plugins:

Set of all requested plugins:
chucknorris 1.2
workflow-step-api 1.14

Set of all requested plugins that will be downloaded:
chucknorris 1.2
workflow-step-api 1.14

Set of all existing plugins and plugins that will be downloaded:
chucknorris 1.2
workflow-step-api 1.14
Done

Find the section in your output titled Set of all requested plugins that will be downloaded. This section is the list of plugins that will need to be added to plugin-catalog.yaml to successfully install the plugins.yaml.

You may get significantly more output than the example, especially in the “Bundled Plugins” and “Set of all existing plugins and plugins that will be downloaded” sections.

CasC API endpoints

Configuration as Code (CasC) for Controllers has several HTTP endpoints for retrieving and updating CasC configurations.

See CasC bundle management on Operations Center HTTP API for more information.

CasC CLI commands

Configuration as Code (CasC) for Controllers has several CLI commands for retrieving and updating CasC configurations.

See CasC bundle management on Operations Center CLI for more information.

Troubleshooting

Delaying Configuration as Code (CasC) for Controllers configuration for Jenkins to load global configuration

Jenkins 2.199 introduced a check to prevent saving global configurations before they are loaded. Configuration as Code (CasC) for Controllers needs to apply global configurations before Jenkins loads jobs to correctly reference any global state. Therefore, until JENKINS-51856 is implemented, there is a race condition where Jenkins may fail to start when used with the Configuration as Code plugin.

If you encounter the race condition, Jenkins will fail to start with an exception message similar to the following:

SEVERE	jenkins.InitReactorRunner$1#onTaskFailed: Failed ConfigurationAsCode.init
java.lang.IllegalStateException: An attempt to save the global configuration was made before it was loaded

The workaround for this race condition is to delay Configuration as Code (CasC) for Controllers configuration to give Jenkins time to load the global configuration.

To enable this delay, set the io.jenkins.plugins.casc.ConfigurationAsCode.initialDelay system property to the amount of delay time in milliseconds. This delay time value will be dependent on aspects of your system (cpu/disk) and configuration.

To find a value that will work with your system, start with 5000 (5 seconds) and increment by 2000 (2 seconds) until the issue is corrected, then add 1000 (1 second) to the final value for extra safety.

Enabling Configuration as Code (CasC) for Controllers configuration delay on a client controller

Applying the workaround system property to a client controller depends on the client controller installation method.

Using the same way other system properties have been added to the init script:

In the same way other system properties have been added to the init script, set the -Dio.jenkins.plugins.casc.ConfigurationAsCode.initialDelay system property to the amount of delay time in milliseconds.

Validating the bundle deployment in Operations Center

You can check that the configuration bundle is properly deployed to the Operations Center server using an HTTP client tool such as cURL. Use the tool to fetch the bundle.yaml using the URL you entered into the casc-bundle-link.yaml file. To authenticate the request, you will also need to provide the token value from the casc-bundle-link.yaml file as an HTTP header named X-CasC-Token.

Example request with authentication token

curl -v -H "X-CasC-Token: abc123de-f456-7891-gh23-i4jkl45m6n7o" \
http://oc1.example.org:8180/config-bundle/bundle-1

This request should return the bundle.yaml file from the configuration bundle in the directory named bundle-1.

If the bundle.yaml file is not returned and you received the following error: No response/connection refused/timeout.

Check that the Operations Center server is running.
Check that the hostname matches the Operation Center’s.
Check that the port in the URL matches the Operations Center’s port.
Check whether a firewall between the client and the Operation’s Center could be blocking the connection.

If the bundle.yaml file is not returned and you received the following error: Wrong bundle returned. Check that the bundle files were placed into the correct directory on the Operations Center server.

If the bundle.yaml file is not returned and you received the following error: HTTP status code 404/Not Found returned.

This can happen when either the URL path was incorrect, or the token was not found.

Check that the URL matches the format specified above, and that the final part matches the name of the directory containing the configuration bundle.
Check that the token value provided matches the one for this bundle in the bundles list in Operations Center under Manage Jenkins > Configuration as Code Bundles.

Support bundles for CasC

When generating a support bundle for a controller, you can include the CloudBees Configuration as Code bundle within the support bundle. Optionally, you can also enable Support Bundle Anonymization from the Configure Global Security screen, to automatically anonymize metadata within the YAML files that are included in the generated support bundle. For more information, see Generating a support bundle.

Configuration as Code (CasC) for Controllers

Introducing Configuration as Code (CasC) for Controllers

Understanding configuration bundles

Creating a configuration bundle

bundle.yaml

Sample bundle.yaml file

jenkins.yaml

Sample jenkins.yaml file

plugins.yaml

Sample plugins.yaml file

plugin-catalog.yaml

Sample plugin-catalog.yaml file

items.yaml

Sample items.yaml file

rbac.yaml

Sample rbac.yaml file

Exporting a CasC bundle

Prerequisites

Example exported bundle files

Adding a CasC bundle to Operations Center

Example directory for multiple CasC bundles

Loading CasC bundles from a SCM tool

Prerequisites

Creating a job in Operations Center

Triggering the job automatically using Webhooks

Updating a CasC bundle

Understanding risks related to updating CasC files

Risks when updating the bundle.yaml file

Risks when updating the plugins.yaml file

Risks when updating the plugin-catalog.yaml file

Risks when updating the jenkins.yaml file

Using hot reload on a configuration bundle

Setting up a client controller using CasC

Downloading the casc-bundle-link.yaml file

Configuring client controllers with the casc-bundle-link.yaml file

Viewing bundles in Operations Center

Assigning a bundle to a controller

Re-generating a bundle token

Creating folders with CasC

Prerequisites

Exporting folder configurations

Example CasC configuration bundle with folders

bundle.yaml

plugins.yaml

plugin-catalog.yaml

jenkins.yaml

rbac.yaml

items.yaml

Configuring RBAC with CasC

Prerequisites

Required setup

Exporting RBAC configurations

Example CasC configuration bundle with RBAC

bundle.yaml

plugins.yaml

plugin-catalog.yaml

jenkins.yaml

rbac.yaml

Determining plugin compatibility

Plugin Catalog limitations in CasC

Advanced topics

Enabling HTTPS

Example startup parameters

Using a self-signed certificate

Calculating plugin dependencies

Prerequisites

Sample output file with list of plugins

CasC API endpoints

CasC CLI commands

Troubleshooting

Delaying Configuration as Code (CasC) for Controllers configuration for Jenkins to load global configuration

Enabling Configuration as Code (CasC) for Controllers configuration delay on a client controller

Validating the bundle deployment in Operations Center

Example request with authentication token

Support bundles for CasC

Risks when updating the `bundle.yaml` file

Risks when updating the `plugins.yaml` file

Risks when updating the `plugin-catalog.yaml` file

Risks when updating the `jenkins.yaml` file

Downloading the `casc-bundle-link.yaml` file

Configuring client controllers with the `casc-bundle-link.yaml` file