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 three types of validation messages: ERROR, INFO, 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.
An INFO message lists:
- the validations run during the validation check
- the total number of validations run during the validation check
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.

The validation messages displayed depend on whether Quiet mode is set for your CasC configuration. Quiet mode only displays error and warning messages on the Configuration as Code export and update screen. By default, Quiet mode is not set and all validation messages (ERROR, INFO, and WARNING) are displayed.

To configure quiet mode:

From the operations center dashboard, select Manage Jenkins.
Select System.
On the System Configuration screen, navigate to Configuration as Code validation visualization mode and select Quiet mode.

Figure 1. Configure quiet mode
Select Save.

Each bundle validation message that displays on the Configuration as Code export and update screen includes the type of validation, the total number of validations ran, a general validation code, and a descriptive message.

Figure 2. Bundle validation message (without validation messages - Quiet mode)

Figure 3. Bundle validation messages (with validation messages)

WARNING message
ERROR validation message
INFO validation messages

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.
SCHEMA	Validates YAML files in the bundle against their schemas.
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.
SCHEMA	ERROR	Example: Errors (2) validating `rbac.yaml`: error 1, error 2	YAML content of that file (`rbac.yaml` in the example) is not valid according to CloudBees CI accepted schema.
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.

Disabling remote validations

Disable remote validations for all bundles to prevent any performance issues if availability patterns have been defined that match a large number of connected controllers.

To disable remote validations:

Select Manage Jenkins on the operations center dashboard. The Manage Jenkins screen displays.
Select CloudBees Configuration as Code bundles. The CloudBees Configuration as Code bundles management screen displays.
Navigate to the General Settings tab and select Disable remote validation for all bundles.

Figure 4. Disable remote validation for all bundles
Select Save Changes.

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 5. CloudBees Configuration as Code export and update
Select CloudBees Configuration as Code export and update.
Select Original bundle.

Figure 6. 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 7. 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 CasC bundle update log within the support bundle. For more information, see Generating a support bundle.