Validate a CasC bundle

Once you create a CasC bundle, whether it was created manually or exported and transformed, you should validate the bundle before distributing and using it to configure a new CloudBees CI instance.

CloudBees CI immediately validates the bundle when you apply it to configure a new instance, operations center, or controller, and displays the validation result in the Update log tab within the Manage Jenkins CloudBees Configuration as Code export and update screen.

However, if you haven’t gone through the validation process before using the bundle, and the validation fails with errors, the CloudBees CI instance, operations center, or controller might not start correctly.

Types of CasC bundle validations

Before presenting the recommended practices for the validation process, it is essential to understand the various types of validations that can be performed on a CasC bundle. CasC bundles can be validated in two different ways:

Structural validation: Structural validations verify the bundle structure and syntax. If the bundle is invalid from a structural point of view, the bundle cannot be applied to a CloudBees CI instance. Structural validations review the bundle structure, such as the presence of required files, the correct format of the files, and the correct syntax of the YAML files.
Runtime validation: Runtime validations verify if the configuration described in the bundle is valid and can be applied to a specific CloudBees CI instance, which is up and running with a specific configuration and plugins already installed. They verify the the configuration of the instance, the items to create or update, and the installed plugins. This type of validation requires the plugins for the configuration and items in the bundle to be installed in the instance to be successful. As a result of a runtime validation, you can get validation messages, warnings, and errors. Warnings allow the bundle to be applied, but errors prevent the bundle from being applied to a CloudBees CI instance.

Directly applying a CasC bundle to a CloudBees CI instance without performing a runtime validation may lead to a failed instance start.

Refer to Troubleshoot CasC for the operations center and Troubleshoot CasC for controllers to understand the possible validation messages, warnings, and errors.

Validate a new CasC bundle

New CasC bundles, whether created manually or exported and transformed, can be validated in various ways and locations.

You can validate a new CasC bundle:

Without distributing the bundle
Distributing the bundle

Without distributing the bundle

CloudBees recommends validating the bundle immediately after creating it, and before distributing it, and using it to configure a new CloudBees CI instance, operations center, or controller.

Figure 1. Validation workflow for new CasC bundles

Regardless of whether the new bundle uses inheritance or not, you can perform different validations without distributing the bundle.

You can use the operations center’s pre-validate-bundle API endpoint or the CLI command to perform a structural validation of the bundle.
You can use the casc-bundle-validate API endpoint or the CLI command to perform a complete validation (structural and runtime) against a running CloudBees CI instance.

Prevalidate a new CasC bundle using the operations center

You can use the pre-validate-bundle API endpoint or the CLI command to perform a structural validation of a new CasC bundle. This method calculates the effective bundle and performs additional validations if the bundle is a controller bundle that is already added to the operations center and used by controllers. However, with an unused new bundle, the validation is only structural.

Prevalidation API endpoint request to perform a structural validation

curl --user "<user>:<user-token>" \ \<1>
 --data-binary @</path/to/bundle.zip> \ \<2>
 -H "Content-Type: application/zip;charset=utf-8" \
 -H "Accept: application/json" \
 -XPOST "https://<your-oc-url>/casc-bundle/pre-validate"\<3>▼

1	Replace `<user>` and `<user-token>` with the authentication data for a user with the CasC Checkout permission. Refer to CasC permissions for more information.
2	Replace `</path/to/bundle.zip>` with the path to the CasC bundle that you want to validate.
3	Replace `<your-oc-url>` with the URL of your operations center instance.

Prevalidation CLI command to perform a structural validation

java -jar jenkins-cli.jar \
-auth <user>:<user-token> \ \<1>
casc-pre-validate-bundle \
-s https://<your-oc-url>/ \<2>
-webSocket < </path/to/bundle.zip> \<3>▼

1	Replace `<user>` and `<user-token>` with the authentication data for a user with the CasC Checkout permission. Refer to CasC permissions for more information.
2	Replace `<your-oc-url>` with the URL of your operations center instance
3	Replace `</path/to/bundle.zip>` with the path to the CasC bundle that you want to validate.

Once you have the prevalidation results, you can iterate through this process if necessary, until you have a bundle ready with no structural issues to be distributed (local folder or SCM) and used to configure a new controller.

Validate a new CasC bundle against a running CloudBees CI instance

CasC bundles can be fully validated (structural and runtime validations) against a running CloudBees CI instance without applying the bundle using the instance casc-validate-bundle API endpoint or CLI command. This type of validation requires a raw or effective bundle, and Controller CasC bundles may use inheritance. Therefore, before validating a new CasC bundle that uses inheritance against a running instance to perform a complete validation (structural and runtime), you should first calculate the effective bundle, which is the bundle that results from merging a bundle and its parents.

Bundle inheritante is only available for controller bundles.

To calculate the effective bundle, you can use the API endpoint or the CLI command provided by an operations center.

API endpoint request to calculate the effective bundle

curl --user "<user>:<user-token>" \ \<1>
 --data-binary @</path/to/bundle.zip> \ \<2>
 -H "Content-Type: application/zip;charset=utf-8" \
 -XPOST "https://<your-oc-url>/casc-bundle/get-effective-bundle?bundle=casc-bundle-java" \ \<3>
 --output <effective-bundle-file.zip>\<4>▼

1	Replace `<user>` and `<user-token>` with the authentication data for a user with the CasC Checkout permission. Refer to CasC permissions for more information.
2	Replace `</path/to/bundle.zip>` with the path to the CasC bundle that uses inheritance.
3	Replace `<your-oc-url>` with the URL of your operations center instance.
4	Replace `<effective-bundle-file.zip>` with the path where you want to save the calculated effective bundle.

Jenkins CLI command to calculate the effective bundle

java -jar jenkins-cli.jar \
-auth <user>:<user-token> \ \<1>
casc-get-effective-bundle \
-s https://<your-oc-url>/ \<2>
-webSocket -b <bundle-id> < </path/to/bundle.zip> \<3>▼

1	Replace `<user>` and `<user-token>` with the authentication data for a user with the CasC Checkout permission. Refer to CasC permissions for more information.
2	Replace `<your-oc-url>` with the URL of your operations center instance.
3	Replace `<bundle-id>` with the ID of the CasC bundle that uses inheritance and `</path/to/bundle.zip>` with the path to the CasC bundle that uses inheritance.

With the raw or effective bundle available, the validation API endpoint and CLI allow you to perform a complete validation (structural and runtime) against a running CloudBees CI instance, operations center, or controller. To perform this complete validation, you can choose one of the following options:

Use an already running instance as similar as possible to the target instance you want to configure with the bundle. In this context "as similar as possible" means:
- A running operations center instance to validate operations center bundles, or a running controller instance to validate controller bundles.
- A production instance with the same CloudBees CI version and plugin versions as the target instance you want to configure with the bundle.
- A test environment with the same CloudBees CI version and plugin versions as the production environment.
- The production instance itself, if possible, to validate the bundle against the production instance configuration and plugins.
For controller CasC bundles, create a new temporary controller with the same CloudBees CI version and plugin versions as the target controller you want to configure with the bundle. You can delete the temporary controller after the validation is completed.

Validation API endpoint request to perform a complete validation

curl --user "<user>:<user-token>" \ \<1>
--data-binary "@</path/to/your/bundle.zip>" \ \<2>
-H "Content-Type: application/zip;charset=utf-8" \
-XPOST "https://<your-instance-url>/casc-bundle-mgnt/casc-bundle-validate"
 -H "Content-Type: application/zip;charset=utf-8"▼

1	Replace `<user>` and `<user-token>` with the authentication data for a user with the CasC Administer permission. Refer to CasC permissions for more information.
2	Replace `</path/to/your/bundle.zip>` with the path to the CasC bundle that you want to validate.
3	Replace `<your-instance-url>` with the URL of your CloudBees CI instance you want to validate (structural and runtime validations) the bundle against.

The casc-bundle-validate API endpoint requires the ci-plugin:[cloudbees-casc-client] to be installed in the instance.

Validation CLI command to perform a complete validation

java -jar jenkins-cli.jar \
-auth <user>:<user-token> \ \<1>
casc-bundle-validate \
-s https://<your-instance-url>/ \ \<2>
-webSocket casc-bundle-validate < </path/to/your/bundle.zip>▼

1	Replace `<user>` and `<user-token>` with the authentication data for a user with the CasC Administer permission. Refer to CasC permissions for more information.
2	Replace `<your-instance-url>` with the URL of your CloudBees CI instance that you want to validate (structural and runtime validations) against the bundle.
3	Replace `</path/to/your/bundle.zip>` with the path to the CasC bundle that you want to validate.

Once you have the validation results, you can iterate through this validation process if necessary, until you have a bundle ready to be distributed (local folder or SCM) and used to configure a new CloudBees CI instance, operations center, or controller.

Refer to CasC CLI commands or CasC API requests for more information about the CLI commands and API requests.

Distributing the bundle

Distributing a CasC bundle means making it available to all the CloudBees CI instances using the bundle, whether it is a new bundle or an updated bundle, but without applying it to the CloudBees CI instances.

CasC bundles are also validated when they are distributed and made available to operations centers and controllers.

If the bundle is a controller bundle, and you add the controller bundle to the operations center to distribute it, the operations center performs a structural validation of the bundle. Additional validations are performed if the bundle is already used by any controller. Those validations are introduced later in this document. The results of these validations display in the operations center, in the Manage Jenkins Configuration as Code bundles screen.

Validate a CasC bundle already in use

Once you apply a CasC bundle to configure a CloudBees CI instance, operations center, or controller, it is considered already in use. All CasC bundles are automatically validated when they are applied to configure a CloudBees CI instance, and the validation results are displayed in the Update log tab within the Manage Jenkins CloudBees Configuration as Code export and update screen.

However, bundles and CloudBees CI change over time, and you might need to update a CasC bundle that has already been distributed and used to configure a CloudBees CI instance. The validation process for bundles already in use is similar to that for new bundles, but with some differences. Two different scenarios are:

Without distributing the bundle
Distributing the bundle

Without distributing the bundle

CloudBees recommends validating all bundles that you update, even if the bundle has already been used, before distributing and making it available again to all the CloudBees CI instances using the bundle.

To validate bundles that are already in use, utilize the API endpoint or the CLI commands as described in the Validating a new CasC bundle section, and iterate until you achieve a bundle ready to be distributed and used to update a CloudBees CI instance configuration.

NOTE: If the CasC bundle has been distributed from the operations center and previously used to configure a controller, utilizing the operations center’s pre-validate-api API endpoint results in a complete validation (both structural and runtime) against all of the controllers that are using the bundle. The results of these validations are part of the API response, and you can use them to determine if the bundle is ready to be distributed and used to update the configuration of the controllers.

Distributing the bundle

When you distribute a completely new CasC bundle, structural validations are performed if the bundle is a controller bundle and you add the controller bundle to the operations center, using the operations center as a distribution point to configure controllers. However, if the bundle is already in use when you update a CasC bundle and distribute it, additional validations occur, depending on the bundle type:

A complete validation (structural and runtime) displays in the Update log tab within the Manage Jenkins CloudBees Configuration as Code export and update screen for all the instances using the bundle. You can determine if the bundle is ready to be update the configuration of the CloudBees CI instance, operations center, or controller, and if it can be applied without issues.
If the bundle is a controller bundle added to operations center, the operations center performs a structural validation of the bundle that displays in the Manage Jenkins Configuration as Code bundles screen.
If you are using an SCM as a bundle location to distribute a controller bundle from the operations center and you create a pull request with the changes to the bundle, if your GitHub App authentication for your GitHub Organization is enabled, GitHub checks are executed, and perform a prevalidation (structural validation) for all the bundles in the pull request.
If you are using the CasC Controller Bundle Service to distribute CasC bundles to controllers, GitHub checks are also executed and perform a prevalidation for all the bundles in the pull request when you create a pull request with the new version of the bundles.

CasC bundle validation limitations

CasC bundle validation does not guarantee that the bundle will work as expected when applied to a CloudBees CI instance. The validation process depends on the CloudBees CI version and the plugin versions installed in the CloudBees CI instance. Some limitations due to the nature of the CasC bundle validation process may arise, including:

If you used a CasC bundle to configure a CloudBees CI instance without any problems, and you upgrade the instance, there is no guarantee that the bundle will work as expected after the upgrade, as new CloudBees CI versions and plugin versions may introduce new features, changes or deprecations that affect the bundle. If possible, test the CasC bundle in a test environment with the same CloudBees CI version and plugin versions.
If you update a CasC bundle with new plugins and items that depend on those new plugins (for example, and Organization folder that depends on the GitHub Branch Source plugin), the bundle will fail to validate (runtime validation) against a CloudBees CI instance without those plugins installed. To navigate around these limitations, CloudBees recommends the following:
1. Update the CasC bundle with the new plugins but without the items that depend on those new plugins.
2. Apply the bundle to a CloudBees CI instance, operations center or controller, with the new plugins installed.
3. Update the CasC bundle again, this time including the items that depend on the new plugins.
4. Apply the bundle to the CloudBees CI instance, operations center or controller, and verify that the items are created as expected. As you are only adding new items this time, you may be able to perform a hot reload of the bundle (applying the bundle without restarting the instance).

Refer to Troubleshoot CasC for the operations center and Troubleshoot CasC for controllers for more information about validation, and to understand the possible validation messages, warnings, and errors.