You can use HTTP API endpoints to manage CasC bundles and create a new item in the operations center based on a CasC items.yaml file.
Authentication and authorization
To access the CasC API, you need an API authentication token and administrator access rights. Refer to API authentication for more information.
Endpoints and methods
| Endpoint | Description | Parameters | Prerequisites | ||||
|---|---|---|---|---|---|---|---|
GET | Lists all available controller CasC bundles on the operations center. | None. |
| ||||
GET | Returns the same information that is available from the Update log tab on the CloudBees Configuration as Code export and update screen. | None. |
| ||||
GET | 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 | None. |
| ||||
GET | Downloads the client controller linkfile. |
|
| ||||
GET | Generates the entire CasC bundle as plain text and all of the YAML files are concatenated. | None. |
| ||||
GET | Generates the zip file that contains all of the exported CasC YAML files. If a bundle update is available, you can issue the | None. |
| ||||
POST | Regenerates the controller bundle token and returns the new bundle information when successful. |
|
| ||||
POST | Specifies the availability pattern, to define the path to controllers that can use the bundle. |
|
| ||||
POST | Specifies the default global availability pattern behavior for the controller CasC bundle. |
|
| ||||
POST | Uses the availability pattern defined in the |
|
| ||||
POST | Assigns a new controller path and returns the new bundle information when successful. For this command to be successful, you must first define the availability pattern for the bundle by sending the |
|
| ||||
POST | Specifies a default bundle that is pre-selected in the operations center controller configuration screen when setting up a new controller. 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 Specifying a default bundle does not assign the bundle to a controller. When setting up a new controller in the operations center, you must click Save or Apply from the controller configuration screen to assign the pre-selected bundle to the controller. |
|
| ||||
POST | Validates a bundle stored in the operations center. |
|
| ||||
POST | Applies the bundle update without restarting the instance when possible. | None. |
| ||||
POST | Creates a new item in the operations center based on an |
|
| ||||
POST | Assigns a new controller path and returns the new bundle information when successful. For this command to be successful, you must first define the availability pattern for the bundle by sending the
|
|
| ||||
POST | Exports the current CasC bundle as a zip file. | None. |
| ||||
POST | Downloads the contents of the YAML file. | None. |
| ||||
POST | Exports the item to the CasC YAML file. The path should include the Uniform Resource Identifier (URI) to the job.
You can also end the request with the file name of the section: | None. |
| ||||
POST | Validates a bundle against an instance. The bundle must be a .zip file. |
|
|
Request examples
| In the request examples "admin" is the name of the user attempting to send the request and "https://my-operations-center.com/" is the operations center URL. |
| Endpoint | Request example |
|---|---|
GET | |
GET | |
GET | |
GET | |
GET | |
GET | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
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-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"
}
]
}{
"update-available": true,
"versions": {
"current-bundle": {
"version": "2",
"validations": []
},
"new-version": {
"version": "5",
"valid": true,
"validations": [
"WARNING - [CATALOGVAL] - More than one plugin catalog file used in zip-core-casc-1652255664849. Using only first read file."
]
}
},
"update-type": "RELOAD"
}{
"url": "https://my-operation-center.com/zip-bundle/ 0e9f58f059c8d91170d4c4b68c6766fb/folder1/{CTRL}1"
"token": "bc1d6f32-0d6d-4580-b25c-423282ea3925"
}# bundle.yaml
apiVersion: "1"
id: "jenkins"
description: "Autogenerated bundle descriptor"
version: "1"
jcasc:
- "jenkins.yaml"
plugins:
- "plugins.yaml"
catalog:
- "plugin-catalog.yaml"
rbac:
- "rbac.yaml"
items:
- "items.yaml"
# jenkins.yaml
...{
"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": ""
}{
"controllers": [
"folder1/controller1",
"folder1/controller2"
]
}{
"visibility": true
}{
"controllers": [
"folder1/controller1",
"folder1/controller2"
]
}{
"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": ""
}{
"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": []
}
]
}{
"reloaded": true
}{
"basePath": "/folder1"
}{
"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": ""
}Instead of a response, the zip bundle is downloaded to the download.zip file.apiVersion: "1"
id: "oc"
description: "Operations Center Bundle"
version: "1.3"
items:
- "items/items.yaml"
catalog:
- "catalog/plugin-catalog.yaml"kind: folder
name: self-service
description: Managed Controller Self Service folder
displayName: Self Service
groups:
- roles:
- name: selfservice
grantedAt: current
name: SelfService
properties:
- envVars: {
}
- kubernetesFolderProperty: {
}
- itemRestrictions:
allowedTypes:
- com.cloudbees.opscenter.server.model.ManagedMaster
filter: true{
"valid": false,
"validation-messages": [
"ERROR - [APIVAL] - 'apiVersion' property in the bundle.yaml file must be an integer.",
"WARNING - [JCASC] - It is impossible to validate the Jenkins configuration. Please review your Jenkins and plugin configurations. Reason: jenkins: error configuring 'jenkins' with class io.jenkins.plugins.casc.core.JenkinsConfigurator configurator"
]
}Response model
| Element | Type | Description |
|---|---|---|
availableFor | array of objects | Controllers that can be assigned to the bundle based on the availability pattern. |
availabilityPatternFromYaml | string | Returns |
bundles | array of objects | All bundles available on the operations center. |
controllers | array of objects | The full paths of all controllers that can use the bundle. |
linkFileContent | string | Contains two entries in string format wrapped 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, |
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, |
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. |
visibility | string | The default global availability pattern behavior for the bundle. |
Status and error codes
| Code | Description |
|---|---|
200 | Success |
403 | Not authorized. Administrator permission required. |
404 | The provided controller path, endpoint, or method cannot be found. |
500 | Server error. |
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.
-
Send the GET
/casc-bundle/listrequest to list all available CasC bundles on the operations center. For example:curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/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: Send the POST
/casc-bundle/set-availability-patternrequest to define the path to the controllers that can use the bundle. For example:curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-availability-pattern?bundleId=casc-bundle-java®ex=folder1.*"If successful, a list of all controllers that can use the bundle is returned:
{ "controllers": [ "folder1/controller1", "folder1/controller2" ] } -
Option 2: Send the POST
/casc-bundle/set-global-availability-pattern-behaviorrequest 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:curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-global-availability-pattern-behavior?visibility=true"If successful, the default global availability pattern behavior is returned:
{ "visibility": true }
-
-
Send the POST
/casc-bundle/set-controller-to-bundlerequest to assign a bundle to a controller. For example:curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-controller-to-bundle?bundleId=casc-bundle-java&controllerPath=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": "" } -
Send the GET
/casc-bundle/listrequest again. For example:curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operation-center.com/casc-bundle/list"The
casc-bundle-javabundle is now assigned tofolder/controller1and also available for assignment tofolder1/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-javaas the default bundle, send the POST/casc-bundle/set-default-bundlerequest:curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operation-center.com/casc-bundle/set-default-bundle?bundleId=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": "" }