bundle.yaml file reference

bundle.yaml

The bundle.yaml file is an index file that describes the bundle and references the other files in the bundle. For controller CasC bundles, it can also be used to optionally configure bundle inheritance and bundle availability.

Property Type Description

string

Required. This bundle’s unique identifier.

The id property is a legacy property that is no longer used. However, it must be included in the bundle.yaml file for backward compatibility.

version

string

Required. The bundle’s version.

If a controller is configured with a bundle using the -Dcore.casc.config.bundle=/path/to/casc-bundle Java system property, this value should be incremented whenever the bundle is modified.

When the operations center generates an effective bundle (after calculating inheritance) for a controller, the version attribute is the checksum of the entire bundle.

For operations centers, this value should be incremented whenever the bundle is modified.

When using the CasC Bundle Retriever for the operations center, you can activate auto-versioning, which replaces the version attribute with the commit hash obtained from your source control management (SCM) system.

apiVersion

string

Required. This is the bundle’s API version. Valid values are apiVersion:1, and apiVersion:2 for CasC plugin management 2.0; otherwise, the bundle would be invalid.

Changes in the apiVersion values must be done with caution, as your CasC bundle may become invalid when updating this value. To understand these risks, refer to Risk while updating your CasC bundle. To learn more about how this property affects plugin management with CasC bundles, refer to Manage plugins with CasC.

description

string

Optional. A helpful description of the bundle.

parent

string

Optional.

This property is only supported for controller CasC bundles; it is not supported for operations center CasC bundles.

The parent bundle’s unique folder name. This property provides bundle inheritance for CasC bundles that are added to the operations center using the CasC bundle location.

This property is not supported if using an HTTP API endpoint or a CLI command to upload a bundle to the operations center or if using the CasC Controller Bundle Service.

With branch and tag support, the value of the parent property can be specified in two ways. For example, assume you have two branches, main and staging. A child bundle is contained in the main branch and a global bundle in both the main and staging branches. The parent value could be specified as follows:

parent: global: This property does not specify a branch. However, because the child bundle is in the main branch, CasC searches for the parent (global) bundle within in the same branch.
parent: main/global: This property value identifies the branch (main). Therefore, CasC searches for the parent bundle in the main branch.
parent: staging/global: This property value identifies the staging branch. Therefore, CasC searches for the parent bundle (global) within the staging branch.

allowCapExceptions

boolean

Optional.

Only for controller CasC bundles. This property is not supported for operations center CasC bundles.

Allows Beekeeper plugin exceptions in the controller’s plugin-catalog.yaml file. For more information, refer to plugin-catalog.yaml and Beekeeper plugin exceptions.

true: Beekeeper plugin exceptions are allowed.
false: (default): Beekeeper plugin exceptions are not allowed.

availabilityPattern

string

Optional.

Only for controller CasC bundles. This property is not supported for operations center CasC bundles.

Specifies the regex availability pattern, to define the full path to one or more controllers in the operations center that can use the CasC bundle. This property provides bundle availability for CasC bundles that are added to the operations center using the CasC bundle location, and is not supported if using an HTTP API endpoint or a CLI command to upload a bundle to the operations center.

This property is not supported if using the CasC Controller Bundle Service to provide CasC bundles to managed controllers.

For more information, refer to Configure bundle availability for controllers.

jcasc

list of strings

Optional. This indicates the bundle contains a jenkins.yaml file.

jcascMergeStrategy

string

Optional. Defines the merge strategy when multiple Jenkins Configuration as Code files are included in a CasC bundle. For more information, refer to Merge Strategy.

errorOnConflict: (default) Returns an exception if there is a conflict in multiple YAML files.
override: Overrides the configuration files according to the loading order. This indicates the bundle contains a jenkins.yaml file.

plugins

list of strings

Optional. This indicates the bundle contains a plugins.yaml file.

catalog

list of strings

Optional.

Only for controller CasC bundles. This property is not supported for operations center CasC bundles.

This indicates the bundle contains a plugin-catalog.yaml file.

items

list of strings

Optional. This indicates the bundle contains a items.yaml file.

itemRemoveStrategy

object

Optional. This property is composed of the removeStrategy for items and the removeStrategy for groups created at the item level.

The itemRemoveStrategy can be specified in the bundle.yaml file, and it applies to every item.yaml file in that bundle.
In the bundle.yaml file, itemRemoveStrategy prevails over the removeStrategy defined in the items.yaml.

This property has two sub-elements: items and rbac. Valid values for these sub-elements are:

items
- none Creates items that do not exist in the instance or updates existing items with the values from the YAML file. Items not declared in the items.yaml file remain as is on the controller or in the operations center.
- sync: Deletes CasC supported items not defined in the items.yaml file. Items in the items.yaml continue in the same way as the none/update strategy.
- remove-supported: Deletes all CasC supported items in the instance and restarts the item creation with the updated bundle.
- remove-all: Deletes all items in the instance and restarts item creation.
rbac The values for this sub-property only apply on groups created for items and not for general groups.
- sync: If the groups already exist but the configuration changes, the new configuration is applied to the groups created for items and the existing groups not present in the new configuration are deleted.
- update: If the groups already exist but the configuration changes, only the existing groups are updated and replaced with the new groups.

If the itemRemoveStrategy is declared, then the items and rbac sub-elements are required. The itemRemoveStrategy property prevails over the removeStrategy property in the items.yaml file.

rbac

list of strings

Optional. This indicates the bundle contains a rbac.yaml file.

rbacRemoveStrategy

object

Optional. Valid values for this property are:

sync: If the role or group already exists, it is updated with the new configuration.
update: If the role or group already exists but the configuration changes, the existing role or group is updated and replaced with the new role or group.

The rbacRemoveStrategy property defined in the bundle.yaml prevails over removeStrategy in the rbac.yaml file.

Example bundle.yaml file

bundle.yaml for a controller

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

bundle.yaml for an operations center

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