Skip to main content

Validating Stack Configurations

Validation is essential for ensuring clean and correct configurations, especially in environments where multiple teams contribute to the development and deployment processes. Atmos enhances this validation process in three significant ways with JSON Schema, OPA policies, and the EditorConfig Checker.

Types of Validation​

Atmos supports three types of native validation.

JSON Schema​

Atmos supports JSON Schema validation, which can validate the schema of configurations such as stacks, workflows, and vendoring manifests. JSON Schema is an industry standard and provides a vocabulary to annotate and validate JSON documents for correctness.

Open Policy Agent (OPA)​

The Open Policy Agent (OPA, pronounced “oh-pa”) is another open-source industry standard that provides a general-purpose policy engine to unify policy enforcement across your stacks. The OPA language (Rego) is a high-level declarative language for specifying policy as code. Atmos has native support for the OPA decision-making engine to enforce policies across all the components in your stacks (e.g., for microservice configurations).

This is powerful stuff: because you can define many policies, it's possible to validate components differently for different environments or teams.

EditorConfig Checker​

The EditorConfig Checker is a tool that ensures adherence to the rules defined in your .editorconfig file. This ensures consistency in coding styles across teams, which is particularly important in collaborative environments. Atmos supports running the EditorConfig Checker to validate the configurations in your project.

Validate Your Configurations​

Validate Components​

To validate an Atmos component in a stack, execute the validate component command:

atmos validate component <component> --stack <stack>
tip

Refer to atmos validate component CLI command for more information on how to validate Atmos components

Check Your Stacks​

To validate all Stack configurations and YAML syntax, execute the validate stacks command:

atmos validate stacks

The command checks and validates the following:

  • All YAML manifest files for YAML errors and inconsistencies

  • All imports: if they are configured correctly, have valid data types, and point to existing manifest files

  • Schema: if all sections in all YAML manifest files are correctly configured and have valid data types

  • Misconfiguration and duplication of components in stacks. If the same Atmos component in the same Atmos stack is defined in more than one stack manifest file, and the component configurations are different, an error message will be displayed similar to the following:

    atmos validate stacks

    The Atmos component 'vpc' in the stack 'plat-ue2-dev' is defined in more than one
    top-level stack manifest file: orgs/acme/plat/dev/us-east-2-extras, orgs/acme/plat/dev/us-east-2.

    The component configurations in the stack manifest are different.

    To check and compare the component configurations in the stack manifests, run the following commands:
    - atmos describe component vpc -s orgs/acme/plat/dev/us-east-2-extras
    - atmos describe component vpc -s orgs/acme/plat/dev/us-east-2

    You can use the '--file' flag to write the results of the above commands to files
    (refer to https://atmos.tools/cli/commands/describe/component).

    You can then use the Linux 'diff' command to compare the files line by line and show the differences
    (refer to https://man7.org/linux/man-pages/man1/diff.1.html)

    When searching for the component 'vpc' in the stack 'plat-ue2-dev', Atmos can't decide which
    stack manifest file to use to get the configuration for the component. This is a stack misconfiguration.

    Consider the following solutions to fix the issue:

    - Ensure that the same instance of the Atmos 'vpc' component in the stack 'plat-ue2-dev'
      is only defined once (in one YAML stack manifest file)

    - When defining multiple instances of the same component in the stack,
      ensure each has a unique name

    - Use multiple-inheritance to combine multiple configurations together
      (refer to https://atmos.tools/core-concepts/stacks/inheritance)

Validate Atmos Manifests using JSON Schema​

Atmos uses the Atmos Manifest JSON Schema to validate Atmos manifests, and has a default (embedded) JSON Schema.

If you don't configure the path to a JSON Schema in atmos.yaml and don't provide it on the command line using the --schemas-atmos-manifest flag, the default (embedded) JSON Schema will be used when executing the command atmos validate stacks.

To override the default behavior, configure JSON Schema in atmos.yaml:

atmos.yaml
# Validation schemas (for validating atmos stacks and components)
schemas:
  # JSON Schema to validate Atmos manifests
  atmos:
    # Can also be set using 'ATMOS_SCHEMAS_ATMOS_MANIFEST' ENV var, or '--schemas-atmos-manifest' command-line arguments
    # Supports both absolute and relative paths (relative to the `base_path` setting in `atmos.yaml`)
    manifest: "stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json"
    # Also supports URLs
    # manifest: "https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json"
  • Instead of configuring the schemas.atmos.manifest section in atmos.yaml, you can provide the path to the Atmos Manifest JSON Schema file by using the ENV variable ATMOS_SCHEMAS_ATMOS_MANIFEST or the --schemas-atmos-manifest command line flag:
ATMOS_SCHEMAS_ATMOS_MANIFEST=stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json atmos validate stacks
atmos validate stacks --schemas-atmos-manifest stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
atmos validate stacks --schemas-atmos-manifest https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
tip

For more details, refer to atmos validate stacks CLI command