You can use the Jenkins CLI to manage CasC bundles and create a new item in the operations center based on a CasC items.yaml file.
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.
|
Commands
| Command | Description | Parameters | Prerequisites | ||||
|---|---|---|---|---|---|---|---|
|
Lists all available controller CasC bundles on the operations center. |
None. |
|
||||
|
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. |
|
||||
|
Regenerates the token and returns the new bundle information when successful. |
|
|
||||
|
Specifies the availability pattern to define the path to controllers that can use the bundle. |
|
|
||||
|
Specifies the default global availability pattern behavior for the controller CasC bundle. |
|
|
||||
|
Uses the availability pattern defined in the |
|
|
||||
|
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 |
|
|
||||
|
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 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. |
Name: bundle-id
|
|
||||
|
Applies the bundle update without restarting the instance, when possible. |
None. |
|
||||
|
Creates a new item in the operations center based on an |
|
|
||||
|
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
|
|
|
||||
|
Validates a bundle stored in the operations center. |
|
|
||||
|
Returns the same information that is available from the Update log tab on the CloudBees Configuration as Code export and update screen. |
None. |
|
||||
|
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, |
|
||||
|
Returns the full validation log for all raw bundles. If the optional |
|
|
||||
|
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. |
None. |
|
||||
|
Returns the full validation log for all effective bundles. If the optional |
|
|
||||
|
Downloads the effective bundle and applies CasC bundle inheritance, so it can be validated on the controller using the |
|
|
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. |
| Command | Command example |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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": "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"
}{
"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{
"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": []
}
]
}{
"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": 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"
]
}{
"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
(...)Response model
| Element | Type | Description |
|---|---|---|
assigned |
boolean |
If |
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. |
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, |
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. |
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-listcommand 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-listIn 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-patterncommand 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-behaviorcommand 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 trueIf successful, the default global availability pattern behavior is returned:
true
-
-
Issue the
casc-bundle-set-controllercommand 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/controller1If 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-listcommand again. For example:java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-listThe
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, issue thecasc-bundle-set-default-bundlecommand:java -jar jenkins-cli.jar -auth admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym -s https://my-operation-center.com/ -webSocket casc-bundle-set-default-bundle -b casc-bundle-javaIf 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":"" }