Troubleshooting CasC for the operations center

Validating CasC bundles

Validation of CasC bundles is performed automatically and if problems are detected, a validation message is returned. Each CasC bundle validation message includes the type of validation, a general validation code, and a descriptive message. For example:

ERROR - [VERSIONVAL] - Missing version property in the bundle.yaml file.

There are two types of validation messages: ERROR and WARNING.

An ERROR indicates a critical problem with the CasC bundle that must be resolved before the bundle can be applied to the instance.
A WARNING indicates the current file is invalid. However, the entire bundle may still be valid.

For example, when creating items, specific plugins must first be installed. If the bundle contains an items.yaml file with the correct kind property for the item type, but the required plugin is not currently installed, a warning is returned. Since the plugin may be installed once the updated bundle has been applied to the instance, the warning indicates that you should verify the required plugin is included in the plugins.yaml file.

Accessing validation messages

For the operations center CasC bundles, validation messages are available in the operations center’s log files and are displayed on the Configuration as Code export and update screen.

General validation codes

The following general validation codes are included in each CasC bundle validation message.

Table 1. General validation codes
Code	Description
APIVAL	Validates the `apiVersion` field in the `bundle.yaml` file.
CATALOGVAL	Validates the `plugin-catalog.yaml` file in the bundle.
CONTVAL	Validates the content of the `bundle.yaml` file and that the bundle is properly described.
DESCVAL	Validates the `bundle.yaml` file.
EMPTY	Validates that the folder containing the bundle is empty.
FORMATVAL	Validates the format of one file in the bundle.
ITEMS	Validates that items can be created.
JCASC	Validates the Jenkins Configuration-as-Code file(s).
LOADERR	Validates that the bundle can be loaded or downloaded before it is applied to the instance. For example, if the operations center is inaccessible and controllers cannot access CasC bundles, `LOADERR` is returned.
NONEXIST	Validates the existence of the CasC bundle folder or the `bundle.yaml` file.
PLUGINVAL	Validates that the plugins in the `plugins.yaml` file can be installed.
RBAC	Validates the Role-Based Access Control (RBAC) configuration.
SEC	Validates that potentially unsecure files are not included in the bundle.
STRUCTURE	Validates the folder containing the bundle in the file system.
UNDEFINED	Undefined validation or unexpected error occurred during a validation. For example, an undefined validation due to legacy code.
VERSIONVAL	Validates the `version` field in the `bundle.yaml` file.

Structural validations

The following validations verify the CasC bundle structure, including the files within the bundle and the content of the bundle.yaml file. The validation is performed when the instance is started and the bundle is applied. If an error is returned, the instance does not start and the validation error is included in the log file.

Table 2. Structural validations
Code	Type	Message	Meaning
APIVAL	ERROR	Missing `apiVersion` property in the `bundle.yaml` file.	The `bundle.yaml` must contain the `apiVersion` property.
APIVAL	ERROR	`apiVersion` property in the `bundle.yaml` file must be a positive integer. `apiVersion` property in the `bundle.yaml` file must be an integer.	The `apiVersion` must always be a positive integer, and use a whole number that is greater than zero. `-1` and `a` are examples of invalid values.
CATALOGVAL	WARNING	The `bundle.yaml` file refers to a `plugin-catalog.yaml` file, which is not supported in the operations center. It will be ignored.	Plugin catalogs are not supported in the operations center. This message informs you that the `bundle.yaml` file has an entry for a `plugin-catalog.yaml` file, but it will be ignored.
CONTVAL	ERROR	Found file-name file specified in the `bundle.yaml` file that is not a folder or a yaml file.	The file is referenced in the `bundle.yaml` file, but it is not a folder or a YAML file, so the entry is invalid.
CONTVAL	WARNING	Not referenced file/folder file-name found in bundle folder.	A file has been detected in the bundle, but it is not directly referenced in the `bundle.yaml` file or the `bundle.yaml` file does not reference a folder that contains the file.
CONTVAL	ERROR	Missing file-name file specified in the `bundle.yaml` file.	The file is referenced in the `bundle.yaml` file, but the file does not exist.
DESCVAL	ERROR	The bundle descriptor is wrong or the `bundle.yaml` file does not exist.	The `bundle.yaml` file cannot be parsed. It is either empty, is not a YAML file, or it does not exist.
DESCVAL	ERROR	Missing `id` property in the `bundle.yaml` file.	The `bundle.yaml` file must contain the `id` property.
EMPTY	ERROR	The CasC bundle folder is empty.	The CasC bundle folder is empty.
NONEXIST	ERROR	The CasC bundle folder does not exist. Impossible to validate.	The folder containing one or more bundles does not exist. This error occurs when the instance is starting and the system property points to a folder that does not exist.
NONEXIST	ERROR	The `bundle.yaml` file is missing.	All bundles should have a `bundle.yaml` file that acts as a bundle descriptor. The `bundle.yaml` file is missing.
PLUGINVAL	WARNING	Plugin plugin-id is not in the CloudBees Assurance Program (CAP) or in applicable plugin catalog(s).	Any plugin in the `plugins.yaml` file should be either in the CAP or referenced in the `plugin-catalog.yaml` file. When this WARNING is raised, you must add the `plugin-id` to the plugin-catalog.yaml` file.
SEC	ERROR	The `bundle.yaml` file refers an entry that is not a folder or a yaml file file.	The `bundle.yaml` file references a file entry that is not a folder or a YAML file.
STRUCTURE	WARNING	The following files have been detected in the bundle folder but they are not yaml files: list of files.	Files in the bundle folder are not YAML files. Bundles can only contain YAML files and/or folders containing YAML files.
STRUCTURE	ERROR	The CasC bundle is not a folder. Impossible to validate.	This error occurs when the instance is starting and the system property points to a file instead of a folder.
STRUCTURE	ERROR	Impossible to read folder X content in the bundle: error message Impossible to read bundle content: error message	An unexpected error occurred when reading the files and folders. Refer to the error message for details.
VERSIONVAL	ERROR	Missing `version` property in the `bundle.yaml` file.	The `bundle.yaml` must contain the `version` property.

Exporting the original CasC bundle

You can export the original CasC bundle and compare it to the current configuration to determine if recent changes may have been incorrectly applied.

Sign in as a user with the Administer permission.
Select Manage Jenkins in the left pane.

Figure 1. CloudBees Configuration as Code export and update
Select CloudBees Configuration as Code export and update.
Select Original bundle.

Figure 2. Original bundle
Select Download to export the original bundle. You can export individual YAML files or export all files in zip format.
Select Current configuration.

Figure 3. Current configuration
Select Download to export the current configuration. You can export individual YAML files or export all files in zip format.
Compare the original bundle to the current configuration to determine if recent changes may have been incorrectly applied.

Support bundles for CasC

When generating a support bundle, you can include the CloudBees Configuration as Code bundle within the support bundle. Optionally, you can also enable Support Bundle Anonymization from the Configure Global Security screen, to automatically anonymize metadata within the YAML files that are included in the generated support bundle. For more information, see Generating a support bundle.

The CasC API plugin must be installed to include the CasC bundle in the generated support bundle.