Configuration as Code (CasC) for Masters
- Introducing CasC
- Understanding configuration bundles
- Creating a configuration bundle
- Exporting a CasC bundle
- Adding a CasC bundle to Operations Center
- Loading CasC bundles from a SCM tool
- Updating a CasC bundle
- Understanding risks related to updating CasC files
- Using hot reload on a configuration bundle
- Setting up a Client Master
- Viewing bundles list
- Creating folders with CasC
- Configuring RBAC with CasC
- Determining plugin compatibility
- Plugin Catalog limitations in CasC
- Advanced topics
- CasC API endpoints
- CasC CLI commands
- Troubleshooting
Configuration as Code (CasC) for Masters 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 CasC
Configuration as Code (CasC) for Masters simplifies the management of a CloudBees Jenkins Platform cluster by capturing the configuration of CloudBees Jenkins Platform masters in human-readable declarative configuration files which can then be applied to a master 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 masters while being centrally managed from CloudBees Jenkins Platform Operations Center.
The process of using Configuration as Code (CasC) for Masters involves the following steps:
-
Create a configuration bundle
-
Make configuration bundle available for distribution by Operations Center
-
Assign a configuration bundle to a master
Understanding configuration bundles
The configuration of a master is described in a collection of YAML files referred to as a Configuration as Code (CasC) for Masters bundle. The Operations Center can store many different configuration bundles representing a selection of predefined masters. Configuration bundles are stored securely on the Operations Center server which manages the secure distribution of the Configuration as Code (CasC) for Masters bundles to the correct masters.
Creating a configuration bundle
To create a new bundle configuration, create each of the files listed below. A Configuration as Code (CasC) for Masters 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 master.
-
plugin-catalog.yaml - (Optional) This file contains the plugin catalog definitions that should be created on the master.
-
items.yaml - (Optional) This file contains the items to be created on the master. 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 |
---|---|---|
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 |
jcasc |
list of strings |
This indicates the bundle contains a |
items |
list of strings |
This indicates the bundle contains a |
catalog |
list of strings |
This indicates the bundle contains a |
rbac |
list of strings |
This indicates the bundle contains a |
jenkins.yaml
This file is the main Configuration as Code (CasC) for Masters configuration file that describes the master. 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 master. 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:
plugin-catalog.yaml
This file defines the catalog of plugins that are available for installation on the master. 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 master 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 masters 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 Master 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
cloudbees-casc-api: (2)
version: X.X (3)
manage-permission: (4)
version: Y.Y (5)
1 | version (required) - must currently have the value 1, which defines the current metadata format for the plugin catalog. |
2 | Adding casc-api-plugin as it is required for using RBAC with CasC, but not included in CloudBees Assurance Program (CAP) yet. |
3 | Replace X.X with most recent version. |
4 | Adding manage-permission to enable the Overall.MANAGE permission. |
5 | Replace Y.Y with most recent version. |
items.yaml
The purpose of the items.yaml
file is to describe the items to be created in the master 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 |
---|---|---|
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 master 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 |
items |
list of objects |
Required. The list of items on the master. |
kind |
string |
Required. Only supported value is “folder”. It defines the kind of item created on the master. |
name |
string |
Required. The name of the item on the master. |
description |
string |
Optional. The description of the item on the master. |
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. |
Sample items.yaml file
removeStrategy:
items: "none"
rbac: "sync"
items:
- kind: "folder"
name: "Acceptance Test Harness"
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"
groups:
- name: "Test A Administrators"
members:
users:
- "john-doe"
roles:
- name: "administer"
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 master. |
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 masters 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 |
---|---|---|
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 |
groups |
list of objects |
Required. The list of RBAC groups available on the master. |
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 master. |
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
filterable: "false"
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 Masters includes a method for exporting Configuration as Code (CasC) for Masters YAML files from pre-existing masters. This method is helpful for creating example files that can then be used to create a new master that can be connected to Operations Center with Configuration as Code (CasC) for Masters. However, the generated bundle should not be used as is and must be updated manually.
The export feature in Configuration as Code (CasC) for Masters relies on OSS Configuration as Code export, which has limitations (See JCasC OSS documentation for more information). In other words, the configuration bundle generated by exporting it from an existing master 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 Masters; 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 masters, it is recommended that the master 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
-
Install the Configuration as Code plugin
-
The
items.yaml
andrbac.yaml
files are only available in CloudBees CI release 2.249.3.Y+.
To Export a Configuration as Code (CasC) for Masters bundle from an existing master:
-
Create a test master 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 master, navigate to Manage Jenkins > Export CloudBees Configuration as Code bundle.
-
Export the files by selecting the export icon next to each file listed.
Figure 1. Export CloudBees Configuration as Code bundleYou can have a configuration bundle without the plugin-catalog.yaml
,plugins.yaml
,items.yaml
, andrbac.yaml
files. If you do not include these files in your bundle, they should not be listed in yourbundle.yaml
file.If the master has CloudBees Assurance Program (CAP)/Beekeeper disabled, the files
plugins.yaml
andplugin-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 master and connect it to Operations Center using a
casc-bundle-link.yaml
file. See Setting up a Client Master for more information.You must remove the obsolete connection details, operationsCenterRootAction
, from thejenkins.yaml
file before connecting it to the Operations Center so new connection details can be established for this new master. Connection details are specific for a master, and cannot be shared between masters. If you release a Client Master the connection details also change. Do not include them unless you really know what you are doing. IfoperationsCenterRootAction
is not present the in thejenkins.yaml
file, Operations Center will create it in the background.
The original test master created in the UI can be deleted as it is no longer needed.
Example exported bundle files
bundle.yaml
id: "0-client-master"
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 - Master 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: "must-have-catalog"
displayName: "Must Have Master Catalog"
configurations:
- description: "Important plugins"
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'}
cloudbees-casc-api: {version: '0.4'}
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 masters 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 Masters 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 Masters 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 Masters bundles to masters from local storage; however, Configuration as Code (CasC) for Masters 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 Masters 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-master-1
-- bundle.yaml
-- jenkins.yaml
-- plugins.yaml
-- plugin-catalog.yaml
- my-master-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 Masters 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 Masters bundles should be available in local storage and ready to be used by masters following the normal procedure.
Triggering the job automatically using Webhooks
One way to trigger a Freestyle job to pull Configuration as Code (CasC) for Masters 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 masters using the Configuration as Code (CasC) for Masters bundle.
Updating a CasC bundle
A configuration bundle can be updated on the Operations Center and will then be automatically distributed to the masters that were initialized with that bundle.
After the initial configuration on startup, there is a background process in the master 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 master 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 master 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 master.
-
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 there are bundle updates available, a message will display with the following three options:
-
Ignore - If you select this option, the old configuration will continue to apply to the master until the next restart.
If you select this option, you will not be able to hot reload this configuration and a restart will be required to apply the new configuration. -
Safe Restart - If you select this option, the master will restart with the new configuration applied.
-
Reload Configuration - If you select this option, the new configuration will be applied without a restart. 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 masters will not get the updates in the bundle.
|
When a Master finds an update to its configuration bundle, an alert is displayed in the Manage Jenkins area.

Apply the update when the master must be restarted; select an appropriate time to do this and then select Safe Restart to have the master restart and apply the updated configuration bundle.
In some instances, a restart will not be required to apply an update to the the master. See Using hot reload on a configuration bundle for more information. |
By default masters 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 Master 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 masters 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 masters 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 master by adding the plugins to this file. Deleting plugins from the file will not remove them from the master.
To remove plugins from the master, delete them in the UI, and before restarting the master, 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. |
-
Navigate to
https://docs.cloudbees.com/plugins
. -
Select Browse and choose Verified and Proprietary in the filter panel.
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 master 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 (ie. 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 master 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 master will continue with its normal startup.
This scenario means plugins are not installed, which might lead to other issues (ie. specific configurations in jenkins.yaml
can not 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 OSS Jenkins Configuration as Code (JCasC) plugin. In other words, all OSS 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 master.
-
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 master 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 (ie. encoded secrets, Operations Center connection details, etc.), so a
jenkins.yaml
is, in general, suitable for a single CloudBees master instance. This might lead to indecipherable secrets, master 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 Masters allows users to reload a configuration file without restarting the instance. Since the Configuration as Code (CasC) for Masters 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 Master
Masters send requests for their bundles through a secure HTTP(S) endpoint in Operations Center. Each master is aware of which bundle it is connected to through the casc-bundle-link.yaml
file that contains the URL of the bundle to use and the access token.
A Client Master is configured using Configuration as Code (CasC) for Masters by providing it with the location of the appropriate bundle and the access token required to grant access. These are provided in a casc-bundle-link.yaml
file. The Client Master 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 Master involves the following steps:
Creating a casc-bundle-link.yaml
file
The connection details needed in the casc-bundle-link.yaml
file, the location of the bundle and the access token required to grant access, are available in Operations Center. To create the casc-bundle-link.yaml
file, download the casc-bundle-link.yaml
file from Operations Center and save it anywhere in the master’s filesystem.
CloudBees recommends the casc-bundle-link.yaml file be saved in the master’s $JENKINS_HOME directory.
|
casc-bundle-link.yaml
file:-
From the Operations Center, navigate to Manage Jenkins > Configuration as Code (CasC) for Masters.
-
Find the configuration bundle in the list.
-
Select the Download link file icon for the configuration bundle to download the
casc-bundle-link.yaml
file. -
Save the file anywhere in the master’s filesystem.
CloudBees recommends the casc-bundle-link.yaml
file be saved in the master’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. |
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: http://oc1.example.org:8080/config-bundle/bundle-1 (or https://oc1.example.org:8080/config-bundle/bundle-1 ).
|
Configuring Client Masters with the casc-bundle-link.yaml
file
The Client Master is directed to use the casc-bundle-link.yaml
file by setting a Java system property. On startup, the Client Master will read the casc-bundle-link.yaml
file, fetch its Configuration as Code (CasC) for Masters bundle from the Operations Center using the details specified in the casc-bundle-link.yaml
file, then initialize itself with the provided configuration.
To point the Client Master 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 Master 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 Master with the correct java system property, open Operations Center and connect the Client Master 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 list
All available bundles are listed under Manage Jenkins → Configuration as Code (CasC) for Masters.
For each bundle the following attributes are displayed:
-
Bundle Name: The bundle name (also used as ID). It matches the name of the directory containing the bundle in the filesystem.
-
URL: The bundle URL where Operations Center exposes its content.
-
Master Path: The full path to the master using the bundle (for more information see Linking a bundle to a master)
-
Token: The access token for the bundle.
-
Actions: The three actions available for each bundle, including:
-
Re-generate the access token.
-
Copy the
casc-bundle-link.yaml
file content to the clipboard. -
Download the
casc-bundle-link.yaml
file.
-
Linking a bundle to a master
The Master Path attribute of a bundle indicates to what master the bundle will be applied. This value must be the full path of the master item in Operations Center and it needs to be set before the master is provisioned. If it’s set after the master is provisioned then a re-provisioning is needed for the configuration to take effect.
The Master Path is the absolute path name (full project name in jobs).
Example | Master Path |
---|---|
A master with the description “CloudBees CI“ and the name “example-casc-master“ created directly in the root of Operations Center. |
modern |
A master with the description “CloudBees CI“ and the name “example-casc-master“ created inside the “folder1” folder. |
folder1/mm-example-casc |
A Team Master with the description “Core on Traditional Platforms“ and the name “astro”. |
Teams/astro |
This parameter is not strictly needed for Client Masters. Client Masters only need to be connected with the correct link file using the download button in the bundles list. However it’s recommended to properly complete this property even for Client Masters for clarity and also for potential features in the future. A bundle is meant to be used in a single master, reusing the same bundle for multiple masters is not recommended. |
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. If there is a master using the regenerated bundle, it will lose access to it.
If the token needs to be re-generated (for example, for security reasons) then the master using the token needs to be
properly reconfigured (if it is a Client Master).
The casc-bundle-link.yaml
file needs to be updated with the new token.
Creating folders with CasC
Configuring folders using Configuration as Code (CasC) for Masters is a Preview feature. |
Configuration as Code (CasC) for Masters 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
-
CloudBees Role-Based Access Control Plugin (Optional)
Exporting folder configurations
Users can export folder configurations from an existing master. 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: folders-casc-catalog
displayName: Folders with casc for preview
configurations:
- description: casc-api-plugin not included in CAP during preview
includePlugins:
cloudbees-casc-api: (1)
version: X.X (2)
manage-permission: (3)
version: Y.Y (4)
1 | Adding casc-api-plugin as it is required but not included in CloudBees Assurance Program (CAP) yet. |
2 | Replace X.X with most recent version. |
3 | Adding manage-permission to enable the Overall.MANAGE permission. |
4 | Replace Y.Y with most recent version. |
jenkins.yaml
jenkins:
systemMessage: "Configured automatically by Configuration as Code for Master - 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 master. |
Configuring RBAC with CasC
Configuring role-based access control (RBAC) with Configuration as Code (CasC) for Masters is a Preview feature. |
Configuring role-based access control (RBAC) with Configuration as Code (CasC) for Masters 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+
Required plugins
Install the following plugins on the master:
The CloudBees CasC API Plugin is not included in CloudBees Assurance Program (CAP) and must be added to a CloudBees CI instance manually by using a Plugin Catalog. |
Required setup
-
Master authorization strategy: To apply RBAC settings to a master using CasC, the master’s authorization strategy must not be inherited from Operations Center.
To enable a master to opt-out of inheriting the Operations Center authorization strategy you must complete the following steps:
-
On Operations Center, select the Allow client masters to opt-out checkbox under Client master 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 masters.
-
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 masters for information on how to customize the authorization strategy for an individual master.
-
-
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 master. 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 master.
-
Manager: Can manage the master 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: rbac-casc-catalog
displayName: Rbac with casc for preview
configurations:
- description: casc-api-plugin not included in CAP during preview
includePlugins:
cloudbees-casc-api: {version: X.X} (1) (2)
manage-permission: {version: Y.Y} (3) (4)
1 | Adding cloudbees-casc-api plugin as it is required but not included in CloudBees Assurance Program (CAP) yet. |
2 | Replace X.X with most recent version. |
3 | Adding manage-permission to enable the Overall.MANAGE permission. This plugin is not required to configure RBAC with CasC. |
4 | Replace Y.Y with most recent version. |
jenkins.yaml
jenkins:
systemMessage: "Configured automatically by Configuration as Code for Master - 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 Masters 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 Masters 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 masters as described in the documentation. However when using it inside a Configuration as Code (CasC) for Masters 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 Masters 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 Masters bundle.
Advanced topics
Enabling HTTPS
The security token and Configuration as Code (CasC) for Masters bundle both contain sensitive information, so it is recommended that they are protected by using HTTPS when sent between the Operations Center and master. 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.
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 Masters bundle.
|
Prerequisites
-
The
plugin.yaml
file from the Configuration as Code (CasC) for Masters 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 master
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 Masters bundle, create aplugins.yaml
file for use with the tool. Rename the Configuration as Code (CasC) for Masters bundle’splugins.yaml
file’s YAML propertyid
toartifactId
as illustrated below:plugins.yaml
from Configuration as Code (CasC) for Masters bundleplugins.yaml
for use with toolplugins: - 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 master
.war
file and the location of yourplugins.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 master .war
file2 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 Masters has several HTTP endpoints for retrieving and updating CasC configurations.
See CasC bundle management on Operations Center for more information.
CasC CLI commands
Configuration as Code (CasC) for Masters has several CLI commands for retrieving and updating CasC configurations.
See CasC bundle management on Operations Center for more information.
Troubleshooting
Delaying Configuration as Code (CasC) for Masters 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 Masters 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 Masters 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 Masters configuration delay on a Client Master
Applying the workaround system property to a Client Master depends on the Client Master 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 (CasC) for Masters).