CasC bundle management on the operations center CLI

Automation

The CasC bundle management on the operations center CLI commands allow users to view the availability patterns and tokens for all CasC bundles on the operations center. They also allow users to assign a bundle to a controller and regenerate tokens.

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.

Commands

Table 1. Commands
CommandDescriptionParameters

casc-bundle-list

Lists all available CasC bundles on the operations center.

None.

casc-bundle-regenerate-token -b (--bundle-id) <bundle id>

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

  • 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.

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.

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

Specifies the default global availability pattern behavior.

  • 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.

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.

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 click Save or Apply from the controller configuration screen to assign the pre-selected bundle to the controller.
  • 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.

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

The casc-bundle-set-master command has been deprecated in version 2.289.2.2 due to offensive terminology. The casc-bundle-set-controller command should be used for all new applications.

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.
If you are using CloudBees CI 2.277.4.2 or 2.277.4.3, if you issue the casc-bundle-set-master command, no bundles are available to assign to the controller. You must first sign in to the operations center as a user with the Administer permission, navigate to the Configuration as Code bundles screen, define the Availability pattern, and then issue the casc-bundle-set-master command to assign a bundle to a controller.
  • 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: master-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

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 2. Command examples
CommandCommand example

casc-bundle-list

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

casc-bundle-regenerate-token -b (--bundle-id) <bundle id>

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

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 -p "folder1/.*"

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-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-set-master -b (--bundle-id) <bundle id> -m (--master-path) <controller path>

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

Response examples

Response examples are formatted for better readability.
casc-bundle-listcasc-bundle-regenerate-token -b (--bundle-id) <bundle id>casc-bundle-set-availability-pattern -b (--bundle-id) <bundle-id> -p (--availability-pattern) <"availability pattern">casc-bundle-set-global-availability-pattern-behavior -v (--visibility) <visibility>casc-bundle-set-controller -b (--bundle-id) <bundle id> -c (--controller-path) <controller path>casc-bundle-set-default-bundle -b (--bundle-id) <bundle id>casc-bundle-set-master -b (--bundle-id) <bundle id> -m (--master-path) <controller path>
{
    "bundles":[
        {
            "linkFileContent":"url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"048f49a4-3b37-4ccf-b536-0cc7a3b148d5\"\n",
            "regex":"folder1/.*",
            "name":"casc-bundle-java",
            "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
            "token":"4b0c02cc-6a7f-4bab-8d8f-38e98684994d"
        }
    ]
}
{
    "linkFileContent":"url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"e33d986f-b11b-43c2-8d20-8109854241e0\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":"4b0c02cc-6a7f-4bab-8d8f-38e98684994d"
}
"folder1/.*"
true
{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"4b0c02cc-6a7f-4bab-8d8f-38e98684994d\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":"4b0c02cc-6a7f-4bab-8d8f-38e98684994d"
}
{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"4b0c02cc-6a7f-4bab-8d8f-38e98684994d\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":"4b0c02cc-6a7f-4bab-8d8f-38e98684994d"
}
{
    "linkFileContent": "url: \"https://my-operation-center.com/config-bundle/casc-bundle-java\"\ntoken: \"4b0c02cc-6a7f-4bab-8d8f-38e98684994d\"\n",
    "regex":"folder1/.*",
    "name":"casc-bundle-java",
    "url":"https://my-operation-center.com/config-bundle/casc-bundle-java",
    "token":"4b0c02cc-6a7f-4bab-8d8f-38e98684994d"
}

Response model

Table 3. Response model
ElementTypeDescription

bundles

array of objects

List of 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.

regex

string

The regex attribute is 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/.*".

name

string

The name is the name of the folder that contains the CasC bundle. For example, casc-bundle-java.

url

string

The url is the bundle URL where the operations center exposes its content.

token

string

The token is the access token for the bundle.

Status and exit codes

Table 4. Status and exit codes
CodeDescription

0

Success

6

Not authorized. Administrator permission required.

3

The provided parameter (bundle id or controller path) does not match with the available bundles.

In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.