Configuration as Code (CasC) CLI

When Configuration as Code (CasC) plugins are installed on the operations center and controllers, you can use the Jenkins CLI tool to perform operations such as managing, validating, or applying CasC bundles, and importing items in your CloudBees CI instance (operations center or controller).

To use the Jenkins CLI tool, first review Jenkins CLI tool.

If you use a CLI command to upload a bundle, the parent and availabilityPattern properties in the controller bundle.yaml file are not supported. The parent and availabilityPattern properties are only supported for configuring bundle availability and for bundle inheritance for controller bundles that are added to the operations center using the CasC bundle location.

Authentication and authorization

To access the Jenkins CLI tool, you need to set up authentication with SSL, or using an API token.

Administrator permissions are required for authorization.

This section include CLI commands for interacting with CloudBees CI Configuration as Code (CasC). Some of these CLI commands are specific to operations center, while other are available for both operations centers and controllers.

Operations center commands

Command Description Parameters Prerequisites

casc-bundle-list

Lists all available controller CasC bundles on the operations center.

None.

CloudBees CI 2.249.2.3 or later
CloudBees CasC Server plugin

casc-bundle-regenerate-token -c (--controller-path) <controller path>

Regenerates the token and returns the new bundle information when successful.

Name: controller-path
- Parameter type: Query string parameter
- Data type: string
- Description: The full path of the controller item in the operations center. For example, folder1/controller1.

CloudBees CI 2.249.2.3 or later
CloudBees CasC Server plugin

The bundle-id parameter has been deprecated in version 2.289.1.2. The controller-path parameter should be used for all new applications.

casc-bundle-set-availability-pattern -b (--bundle-id) <bundle-id> -p (--availability-pattern) <"availability pattern">

Specifies the availability pattern to define the path to controllers that can use the bundle.

Name: bundle-id
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.
Name: availability-pattern
- Parameter type: Query string parameter
- Data Type: string
- Description: The full path to one or more controllers that can use the bundle. This must be a regular expression enclosed in quotation marks, and defines the bundles you can assign to a controller. For example, "folder1/.*" to use the bundle with any controller in the "folder1" folder.

CloudBees CI 2.289.1.2 or later
CloudBees CasC Server plugin

casc-bundle-set-global-availability-pattern-behavior -v (--visibility) <visibility>

Specifies the default global availability pattern behavior for the controller CasC bundle.

Name: visibility
- Parameter type: Query string parameter
- Data type: string
- Description: When the parameter value is true, all CasC bundles that do not have an availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.

CloudBees CI 2.289.2.2 or later
CloudBees CasC Server plugin

casc-bundle-clear-availability-pattern -b (--bundle-id) <bundle id>

Uses the availability pattern defined in the bundle.yaml file and clears the availability pattern for the controller CasC bundle if previously defined.

Name: bundle-id
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

CloudBees CI 2.303.3.3 or later
CloudBees CasC Server plugin

casc-bundle-set-controller -b (--bundle-id) <bundle id> -c (--controller-path) <controller path>

Assigns a bundle to a controller and returns the bundle information when successful.

For this command to be successful, you must first define the availability pattern for the bundle using the casc-bundle-set-availability-pattern or casc-bundle-set-global-availability-pattern-behavior command.

Name: bundle-id
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.
Name: controller-path
- Parameter type: Query string parameter
- Data type: string
- Description: The full path of the controller item in the operations center. For example, folder1/controller1.

CloudBees CI 2.289.2.2 or later
CloudBees CasC Server plugin

casc-bundle-set-default-bundle -b (--bundle-id) <bundle id>

Specifies a default bundle that is pre-selected in the operations center controller configuration screen when setting up a new controller and returns the bundle information when successful.

The default bundle is pre-selected for controllers that match the availability pattern of the default bundle. To set the availability pattern of the default bundle, you can use the casc-bundle-set-availability-pattern or casc-bundle-set-global-availability-pattern-behavior command.

Specifying a default bundle does not assign the bundle to a controller. When setting up a new controller in the operations center, you must select Save or Apply from the controller configuration screen to assign the pre-selected bundle to the controller.

Name: bundle-id

Name: bundle-id
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

CloudBees CI 2.289.2.2 or later
CloudBees CasC Server plugin

casc-uploaded-bundle-validate -b (--bundle-id) <bundle id>

Validates a bundle stored in the operations center.

Name: bundle-id
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.

CloudBees CI 2.332.2.4 or later
CloudBees CasC Server plugin

casc-raw-bundle-validation-log -b (--bundle-id) <bundle id> -c (--with-controller)

Returns the full validation log for all raw bundles. If the optional bundle-id parameter is specified, the output is filtered to only return the validation log for that bundle. If the optional with-controller parameter is specified, the output is enriched with controller effective validation log.

Name: bundle-id (optional)
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.
Name: with-controller (optional)
- Parameter type: Query string parameter
- Data type: boolean
- Description: When set, each raw bundle validation log has a new controllers item that lists all the effective validation logs of the related bundle.

CloudBees CI 2.346.2.1 or later
CloudBees CasC Server plugin

casc-check-out-bundles

Checks out the bundles from all CasC bundle locations to the operations center and returns the JSON array of bundle sources, where each one contains an array of bundles.

Name: timeout (optional)

Description: Checks out timeout in seconds. The default value is 600 seconds and can be set in the global configuration.

CloudBees CI 2.361.3.2 or later
* CloudBees CasC Server plugin

casc-effective-bundle-validation-log -c (--controller-id) <controller id>

Returns the full validation log for all effective bundles. If the optional controller-id parameter is specified, the output is filtered to only return the validation log for that controller.

Name: controller-id (optional)
- Parameter type: Query string parameter, accepts regular expression
- Data type: string
- Description: The name of the controller. For example, controller-.*01.

CloudBees CI 2.346.3.x or later
CloudBees CasC Server plugin

casc-get-effective-bundle -b (--bundle-id) <bundle id> < /path/to/bundle.zip

Downloads the effective bundle and applies CasC bundle inheritance, so it can be validated on the controller using the casc-bundle-validate command. The expected input is a .zip file that contains all child and parent bundles that have changes. The output is the effective bundle in text format.

Name: bundle-id
- Parameter type: Query string parameter
- Data type: string
- Description: The name of the folder that contains the CasC bundle. For example, casc-bundle-java.
path/to/bundle.zip: The name of the path to the local .zip file that contains all the bundles (including the parent bundles) that have changes. For example, /Downloads/casc.zip.

CloudBees CI 2.361.2.1 or later
CloudBees CasC Server plugin

If the branch name follows the Gitflow pattern (for example, feature/branch_name) when the CLI receives a zip file containing the folder structure; escape the / character in the branch name and convert it to _, so the branch feature/branch_name becomes the folder feature_branch_name.

casc-pre-validate-bundle<bundle.zip

Downloads the effective bundle and applies CasC bundle inheritance, so it can be validated on the controller using the casc-bundle-validate command. The expected input is a .zip file that contains the bundles to validate. The output is the validation report.

bundle.zip: The .zip file containing more than one bundle.

CloudBees CI 2.387.1.x or later
CloudBees CasC Server plugin

Commands for operations centers and controllers

Table 2. Commands
Command	Description	Parameters	Prerequisites
`casc-bundle-check-bundle-update`	Checks for bundle updates and returns information about the validation of the current bundle and the new available bundle version. If a bundle update is available, you can issue the `casc-bundle-reload-bundle` command to immediately apply the updated bundle without restarting the instance.	None.	If using CloudBees CI 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.41 If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Client plugin, version 1.44 or later
`casc-bundle-reload-bundle`	Applies the bundle update without restarting the instance, when possible.	None.	If using CloudBees CI 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.41 If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Client plugin, version 1.44 or later
`casc-items-create-items <folder> = < <local-folder/items.yaml>`	Creates a new item in the instance based on an `items.yaml` file stored in the local filesystem.	folder: The full path of the folder in the CloudBees CI instance where the item is created. The folder path must exist in the prior to issuing the command. For example, `/folder1`. To create the item at the root of the instance, you can use `/` as the folder path. local-folder/items.yaml: The full path on the local filesystem to the `items.yaml` file. For example, `/casc/items.yaml`.	If using CloudBees CI 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.41 If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items API plugin, version 1.1.1 or later
`casc-bundle-update-log`	Returns the same information that is available from the Update log tab on the CloudBees Configuration as Code export and update screen.	None.	CloudBees CI 2.346.1.4 or later CloudBees CasC Client plugin, version 1.56 or later
`casc-bundle-validate < /path/to/bundle.zip`	Validates a bundle against an instance. The bundle must be a .zip file.	path/to/bundle.zip: The name of the path to the local .zip file that contains the bundle. For example, `/Downloads/casc.zip`.	CloudBees CI 2.346.1.4 or later CloudBees CasC Client plugin, version 1.57 or later

Command examples

In the command examples, admin is the name of the user attempting to send the request and +https://my-operations-center.com/ is the operations center URL. These examples authenticate using an API token.

Table 3. Command examples
Command	Command example
`casc-bundle-list`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-list` ▼
`casc-bundle-check-bundle-update`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-check-bundle-update` ▼
`casc-bundle-regenerate-token -c (--controller-path) <controller path>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-regenerate-token -c folder1/controller1` ▼
`casc-bundle-set-availability-pattern -b (--bundle-id) <bundle-id> -p (--availability-pattern) <"availability pattern">`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-availability-pattern -b casc-bundle-java -c folder1/controller1` ▼
`casc-bundle-set-global-availability-pattern-behavior -v (--visibility) <visibility>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-global-availability-pattern-behavior -v true` ▼
`casc-bundle-clear-availability-pattern -b (--bundle-id) <bundle id>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-clear-availability-pattern -b casc-bundle-java` ▼
`casc-bundle-set-controller -b (--bundle-id) <bundle id> -c (--controller-path) <controller path>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-controller -b casc-bundle-java -c folder1/controller1` ▼
`casc-bundle-set-default-bundle -b (--bundle-id) <bundle id>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-default-bundle -b casc-bundle-java` ▼
`casc-bundle-reload-bundle`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-reload-bundle` ▼
`casc-items-create-items <oc/folder> = < <local-folder/items.yaml>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-items-create-items /folder1 = < /casc/items.yaml` ▼
`casc-uploaded-bundle-validate -b (--bundle-id) <bundle id>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-uploaded-bundle-validate -b casc-bundle-java` ▼
`casc-bundle-update-log`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-update-log` ▼
`casc-bundle-validate < /path/to/bundle.zip`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-validate < /Downloads/casc.zip` ▼
`casc-raw-bundle-validation-log -b (--bundle-id) <bundle id> -c (--with-controller)`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-raw-bundle-validation-log -b casc-bundle-java -c` ▼
`casc-check-out-bundles`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-reload-bundle` ▼
`casc-effective-bundle-validation-log -c (--controller-id) <controller id>`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-effective-bundle-validation-log -c 'controller-.*01'` ▼
`casc-get-effective-bundle -b (--bundle-id) <bundle id> < /path/to/bundle.zip`	`java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym casc-get-effective-bundle -s https://my-operation-center.com/ -webSocket -b casc-bundle-java < /Downloads/casc.zip` ▼
`casc-pre-validate-bundle < bundle.zip`	`java -jar jenkins-cli.jar casc-pre-validate-bundle < bundle.zip` ▼

Response examples

Response examples are formatted for better readability.

{
    "bundles":[
        {
            "linkFileContent":"url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex":"folder1/.*",
            "name":"casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token":"",
            "usedBy": [
                "folder1/controller1"
            ],
            "availableFor": [
                "folder1/controller1",
                "folder1/controller2"
            ]
        }
    ]
}▼

{
  "update-available": true,
  "versions": {
    "current-bundle": {
      "version": "1",
      "validations": []
    },
    "new-version": {
      "version": "2",
      "valid": true,
      "validations": [
        "WARNING - [PLUGINVAL] - Plugin warning-demo is not in the CloudBees Assurance Program (CAP) or in applicable plugin catalog(s).",
        "INFO - [APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml.",
        "INFO - [CATALOGVAL] - [MultipleCatalogFilesValidator] No catalog validation needed.",
        "INFO - [CATALOGVAL] - [PluginCatalogInOCValidator] No plugin catalog specified.",
        "INFO - [CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated.",
        "INFO - [DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files.",
        "INFO - [ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle.",
        "INFO - [JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle.",
        "INFO - [JCASC] - [JCasCValidator] All configurations validated successfully.",
        "INFO - [SCHEMA] - All YAML files validated correctly against their corresponding schemas",
        "INFO - [STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type.",
        "INFO - [VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml."
      ]
    }
  },
  "update-type": "RELOAD",
  "items": {
    "deletions": []
  }
}▼

{
  "update-available": true,
  "versions": {
    "current-bundle": {
      "version": "1",
      "validations": []
    },
    "new-version": {
      "version": "2",
      "valid": true,
      "validations": [
        "WARNING - [PLUGINVAL] - Plugin warning-demo is not in the CloudBees Assurance Program (CAP) or in applicable plugin catalog(s)."
      ]
    }
  },
  "update-type": "RELOAD",
  "items": {
    "deletions": []
  }
}▼

{
    "linkFileContent":"url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":""
}▼

"folder1/.*"▼

true▼

"folder1/controller1"▼

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":""
}▼

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":""
}▼

Bundle successfully reloaded.▼

Created items on /folder1▼

{
    "valid": false,
    "structureValidations": [
        {
            "level": "WARNING",
            "validationCode": "BUNDLE_STRUCTURE",
            "message": "[STRUCTURE] - The following files have been detected in the bundle folder but they are not yaml files: sample.txt."
        },
        {
            "level": "WARNING",
            "validationCode": "BUNDLE_CONTENT",
            "message": "[CONTVAL] - Not referenced file/folder sample.txt found in bundle folder"
        }
    ],
    "controllerValidations": [
        {
            "controller": "online-ok-controller",
            "controllerStatus": "ONLINE",
            "validations": []
        },
        {
            "controller": "online-ko-controller",
            "controllerStatus": "ONLINE",
            "validations": [
                {
                    "level": "ERROR",
                    "validationCode": "ITEMS",
                    "message": "[ITEMS] - Impossible to parse file name or missing removeStrategy attribute. Please review the file format."
                }
            ]
        },
        {
            "controller": "offline-controller",
            "controllerStatus": "OFFLINE",
            "validations": []
        }
    ]
}▼

{
    "update-log-status": "ENABLED",
    "retention-policy": 10,
    "versions": [
        {
            "version": "6",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00006"
        },
        {
            "version": "5",
            "date": "09 May 2022",
            "errors": 1,
            "warnings": 0,
            "folder": "20220509_00005"
        },
        {
            "version": "4",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00004"
        },
        {
            "version": "3",
            "date": "09 May 2022",
            "errors": 1,
            "warnings": 0,
            "folder": "20220509_00003"
        },
        {
            "version": "2",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00002"
        },
        {
            "version": "1",
            "date": "09 May 2022",
            "errors": 0,
            "warnings": 0,
            "folder": "20220509_00001"
        }
    ]
}▼

{
  "valid": true,
  "validation-messages": [
    "INFO - [STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type.",
    "INFO - [DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files.",
    "INFO - [VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml.",
    "INFO - [APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml.",
    "INFO - [JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle.",
    "INFO - [ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle.",
    "INFO - [CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated.",
    "INFO - [SCHEMA] - All YAML files validated correctly against their corresponding schemas",
    "INFO - [CATALOGVAL] - [PluginCatalogInOCValidator] No plugin catalog specified.",
    "INFO - [PLUGINVAL] - [PluginsToInstallValidator] All plugins are present in the envelope or in the plugin catalog.",
    "INFO - [CATALOGVAL] - [MultipleCatalogFilesValidator] No catalog validation needed.",
    "INFO - [JCASC] - [JCasCValidator] All configurations validated successfully.",
    "INFO - [PLUGINVAL] - [PluginsToInstallValidator] All plugins are present in the envelope or in the plugin catalog."
  ]
}▼

{
  "valid": true
}▼

{
    "validation-log": [
        {
            "bundle-id": "casc-bundle-java",
            "records": [
                {
                    "version": "3",
                    "errors": 0,
                    "warnings": 0,
                    "folder": "20220607_00003",
                    "date": "07 June 2022"
                },
                {
                    "version": "2",
                    "errors": 0,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder."
                    ],
                    "folder": "20220607_00002",
                    "date": "07 June 2022"
                },
                {
                    "version": "1",
                    "errors": 1,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder.",
                        "ERROR - [APIVAL] - 'apiVersion' property in the bundle.yaml file must be an integer."
                    ],
                    "folder": "20220607_00001",
                    "date": "07 June 2022"
                }
            ],
            "controllers": [
                {
                    "controller": "controller-AB01",
                    "records": [
                        {
                            "bundle": "casc-bundle-java",
                            "assigned": true,
                            "version": "0d4b2b2d6f8ba0872a33120a0548a483",
                            "errors": 0,
                            "warnings": 1,
                            "messages": [
                                "WARNING - [PLUGINVAL] - Plugin casc-bundle-java is not in the CloudBees Assurance Program (CAP) or in applicable plugin catalog(s)"
                            ],
                            "folder": "20220725_00002",
                            "date": "25 July 2022"
                        }
                    ]
                }
            ]
        }
    ]
}▼

{
    "remotes: [
        {
            "name": "my-local-bundle-sources",
            "bundles": [
                {
                    "bundleName": "bundle-1",
                    "localText": "2022-09-20T15: 16: 27.318"
                },
                {   "bundleName": "bundle-2",
                    "localText": "2022-09-20T15: 16: 27.318"
                }
            ]
        }
    ]
}▼

{
    "validation-log": [
        {
            "controller": "controller-AB01",
            "records": [
                {
                    "bundle": "casc-bundle-java",
                    "assigned": true,
                    "version": "3",
                    "errors": 0,
                    "warnings": 0,
                    "folder": "20220607_00003",
                    "date": "07 June 2022"
                },
                {
                    "bundle": "casc-bundle-java-02",
                    "assigned": false,
                    "version": "2",
                    "errors": 0,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder."
                    ],
                    "folder": "20220607_00002",
                    "date": "07 June 2022"
                },
                {
                    "bundle": "casc-bundle-java-01",
                    "assigned": false,
                    "version": "1",
                    "errors": 1,
                    "warnings": 1,
                    "messages": [
                        "WARNING - [CONTVAL] - Unreferenced files/folders unknown.yaml found in bundle folder.",
                        "ERROR - [APIVAL] - 'apiVersion' property in the bundle.yaml file must be an integer."
                    ],
                    "folder": "20220607_00001",
                    "date": "07 June 2022"
                }
            ]
        }
    ]
}▼

  # bundle.yaml
  apiVersion: '1'
  description: Effective bundle based on bundle-cb, bundle-ci, casc-bundle-java
  id: casc-bundle-java
  version: d836a9365ffd4efe98380d8c3fb7db28
  plugins:
  - plugins.yaml
  jcasc:
  - jcasc/01-bundle-cb.jenkins.yaml
  - jcasc/02-bundle-ci.jenkins.yaml
  - jcasc/03-casc-bundle-java.jenkins.yaml
  items:
  - jcasc/01-bundle-cb.items.yaml
  - jcasc/02-bundle-ci.items.yaml
  - jcasc/03-casc-bundle-java.items.yaml
  rbac:
  - jcasc/01-bundle-cb.rbac.yaml
  - jcasc/02-bundle-ci.rbac.yaml
  - jcasc/03-casc-bundle-java.rbac.yaml
  catalog:
  - plugin-catalog.yaml
  variables:
  - jcasc/01-bundle-cb.variables.yaml
  - jcasc/02-bundle-ci.variables.yaml
  - jcasc/03-casc-bundle-java.variables.yaml

  ---
  # plugins.yaml
  plugins:
  - id: cloudbees-casc-items-api
  - id: cloudbees-casc-client
  - id: cloudbees-casc-items-controller
  - id: cloudbees-casc-items-common
  (...)

  ---
  # plugin-catalog.yaml
  (...)

  ---
  # jcasc/01-bundle-cb.jenkins.yaml
  (...)

  ---
  # jcasc/01-bundle-ci.jenkins.yaml
  (...)

  ---
  # jcasc/01-casc-bundle-java.jenkins.yaml
  (...)

  ---
  # items/01-bundle-cb.items.yaml
  (...)

  ---
  # items/01-bundle-ci.items.yaml
  (...)

  ---
  # items/01-casc-bundle-java.items.yaml
  (...)

  ---
  # rbac/01-bundle-cb.rbac.yaml
  (...)

  ---
  # rbac/01-bundle-ci.rbac.yaml
  (...)

  ---
  # rbac/01-casc-bundle-java.rbac.yaml
  (...)

  ---
  # variables/01-bundle-cb.variables.yaml
  (...)

  ---
  # variables/01-bundle-ci.variables.yaml
  (...)

  ---
  # variables/01-casc-bundle-java.variables.yaml
  (...)▼

{
  "validations": [
    {
      "bundle": "cm-casc-bundle/core-casc-export-jenkins",
      "result": {
        "valid": true,
        "structureValidations": [
          {
            "level": "INFO",
            "validationCode": "BUNDLE_STRUCTURE",
            "message": "[STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_CONTENT",
            "message": "[CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated."
          },
          {
            "level": "INFO",
            "validationCode": "SCHEMA",
            "message": "[SCHEMA] - All YAML files validated correctly against their corresponding schemas"
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_STRUCTURE",
            "message": "[STRUCTURE] - [ParentValidator] Inheritance validation passed."
          },
          {
            "level": "INFO",
            "validationCode": "DESCRIPTOR",
            "message": "[DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_VERSION",
            "message": "[VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_API",
            "message": "[APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_JCASC_STRATEGY",
            "message": "[JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle."
          },
          {
            "level": "INFO",
            "validationCode": "BUNDLE_ITEM_STRATEGY",
            "message": "[ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle."
          },
          {
            "level": "INFO",
            "validationCode": "PLUGIN_CATALOG",
            "message": "[CATALOGVAL] - [MultipleCatalogFilesValidator] Just one file defining the plugin catalog."
          }
        ],
        "controllerValidations": []
      }
    }
  ]
}▼

{
  "validations": [
    {
      "bundle": "cm-casc-bundle/core-casc-export-jenkins",
      "result": {
        "valid": true,
        "structureValidations": [],
        "controllerValidations": []
      }
    }
  ]
}▼

{
  "valid": true,
  "structureValidations": [
    {
      "level": "INFO",
      "validationCode": "BUNDLE_STRUCTURE",
      "message": "[STRUCTURE] - [FileSystemBundleValidator] All files indicated in the bundle exist and have the correct type."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_CONTENT",
      "message": "[CONTVAL] - [ContentBundleValidator] All files specified in the bundle exist and no unreferenced files indicated."
    },
    {
      "level": "INFO",
      "validationCode": "SCHEMA",
      "message": "[SCHEMA] - All YAML files validated correctly against their corresponding schemas"
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_STRUCTURE",
      "message": "[STRUCTURE] - [ParentValidator] Inheritance validation passed."
    },
    {
      "level": "INFO",
      "validationCode": "DESCRIPTOR",
      "message": "[DESCVAL] - [DescriptorValidator] All files referenced in the descriptor are folders or yaml files."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_VERSION",
      "message": "[VERSIONVAL] - [VersionValidator] Version correctly indicated in bundle.yaml."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_API",
      "message": "[APIVAL] - [ApiValidator] apiVersion correctly indicated in bundle.yaml."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_JCASC_STRATEGY",
      "message": "[JCASCSTRATEGY] - [JcascMergeStrategyValidator] No (optional) jcascMergeStrategy defined in the bundle."
    },
    {
      "level": "INFO",
      "validationCode": "BUNDLE_ITEM_STRATEGY",
      "message": "[ITEMSTRATEGY] - [ItemRemoveStrategyValidator] No (optional) itemRemoveStrategy defined in the bundle."
    },
    {
      "level": "INFO",
      "validationCode": "PLUGIN_CATALOG",
      "message": "[CATALOGVAL] - [MultipleCatalogFilesValidator] Just one file defining the plugin catalog."
    }
  ],
  "controllerValidations": []
}▼

{
  "valid": true,
  "structureValidations": [],
  "controllerValidations": []
}▼

Response model

Table 4. Response model
Element	Type	Description
assigned	boolean	If `assigned` is `true`, the current validation log is the result of an effective bundle that is currently assigned to a controller. If not, `assigned` is `false`. This optional attribute is available with the CloudBees CasC Server plugin, version 1.76 and later.
availableFor	array of objects	Controllers that can be assigned to the bundle based on the availability pattern.
availabilityPatternFromYaml	string	Returns `true` if the availability pattern is defined in the `bundle.yaml` file. Returns `false` if the availability pattern is defined in the UI or using the `casc-bundle-set-availability-pattern` command.
bundles	array of objects	All bundles available on the operations center.
linkFileContent	string	Contains two entries in string format enclosed in quotes and separated by newline characters: url and token. The url is the bundle URL where the operations center exposes its content. The token is the access token for the bundle.
name	string	The name of the folder that contains the CasC bundle. For example, `casc-bundle-java`.
regex	string	The full path to one or more controllers in the operations center that can use the bundle. This must be a regular expression. It defines the bundles you can assign to a controller. For example, `"folder1/.*"`.
token	string	The access token for the bundle.
url	string	The bundle URL where the operations center exposes its content.
usedBy	string	The names of controllers assigned to the bundle.

Status and exit codes

Table 5. Status and exit codes
Code	Description
0	Success
6	Not authorized. Administrator permission required.
3	The provided parameter (bundle id or controller path) does not match the available bundles.

Examples for configuring a controller using CasC

Once the CasC bundle has been configured in the operations center, you can define an availability pattern to make the bundle available to controllers, assign the bundle to a controller, and specify a default bundle.

Issue the casc-bundle-list command to list all available CasC bundles on the operations center. For example:

java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-list▼

In this example, there is one bundle named casc-bundle-java:

{
    "bundles":[
        {
            "linkFileContent":"url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex":"",
            "name":"casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token": "",
            "usedBy": [],
            "availableFor": []
        }
    ]
}▼

Define the availability pattern for the bundle. You have two options:
- Option 1: Issue the casc-bundle-set-availability-pattern command to define the path to the controllers that can use the bundle. For example:
  java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-availability-pattern -b casc-bundle -p "folder1/.*"
  ▼
  If successful, the specified availability pattern is returned:
  "folder1/.*"
  ▼
- Option 2: Issue the casc-bundle-set-global-availability-pattern-behavior command to define the default global availability pattern behavior for bundles that do not have an availability pattern defined. This option provides more flexibility, but is less secure. For example:
  java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-global-availability-pattern-behavior -v true
  ▼
  If successful, the default global availability pattern behavior is returned:
  true
  ▼

Issue the casc-bundle-set-controller command to assign a bundle to a controller. For example:

java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-controller -b casc-bundle-java -c folder1/controller1▼

If successful, the bundle information is returned:

{
    "linkFileContent":"url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":""
}▼

Issue the casc-bundle-list command again. For example:

java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-list▼

The casc-bundle-java bundle is now assigned to folder/controller1 and also available for assignment to folder1/controller2, based on the availability pattern you defined.

{
    "bundles":[
        {
            "linkFileContent":"url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
            "regex":"folder1/.*",
            "name":"casc-bundle-java",
            "availabilityPatternFromYaml": true,
            "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token":""
            "usedBy": [
                "folder1/controller1"
            ],
            "availableFor": [
                "folder1/controller1",
                "folder1/controller2"
            ]
        }
    ]
}▼

Optionally, specify a default bundle to pre-select a bundle in the controller configuration screen when setting up a new controller. For example, to specify casc-bundle-java as the default bundle, issue the casc-bundle-set-default-bundle command:

java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-default-bundle -b casc-bundle-java▼

If successful, the default bundle information is returned:

{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "availabilityPatternFromYaml": true,
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":""
}▼