Troubleshooting CasC for the operations center

6 minute readScalabilityAutomation

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:

  1. From the operations center dashboard, select Manage Jenkins.

  2. Select System.

  3. On the System Configuration screen, navigate to Configuration as Code validation visualization mode and select Quiet mode.

    Configue quiet mode
    Figure 1. Configure quiet mode
  4. 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.

    Bundle validation messages in quiet mode
    Figure 2. Bundle validation message (without validation messages - Quiet mode)
    Bundle validation messages
    Figure 3. Bundle validation messages (with validation messages)
  1. WARNING message

  2. ERROR validation message

  3. 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:

  1. Select Manage Jenkins on the operations center dashboard. The Manage Jenkins screen displays.

  2. Select CloudBees Configuration as Code bundles. The CloudBees Configuration as Code bundles management screen displays.

  3. Navigate to the General Settings tab and select Disable remote validation for all bundles.

    disable remote validation
    Figure 4. Disable remote validation for all bundles
  4. 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.

  1. Sign in as a user with the Administer permission.

  2. Select Manage Jenkins in the left pane.

    CloudBees Configuration as Code export and update
    Figure 5. CloudBees Configuration as Code export and update
  3. Select CloudBees Configuration as Code export and update.

  4. Select Original bundle.

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

  6. Select Current configuration.

    Current configuration
    Figure 7. Current configuration
  7. Select Download to export the current configuration. You can export individual YAML files or export all files in zip format.

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