atmos validate stacks

Purpose

Use this command to validate Atmos stack manifest configurations.

atmos validate stacks --help

Usage

Execute the validate stacks command like this:

atmos validate stacks

This command validates Atmos stack manifests and checks the following:

All YAML manifest files for YAML errors and inconsistencies
- Note: Template files (.yaml.tmpl, .yml.tmpl, .tmpl) are excluded from validation since they may contain template placeholders that are invalid YAML before being rendered
- Template files are still automatically detected and processed during normal operations (imports, etc.)
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 manifests 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 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)

tip

Run atmos validate stacks --help to see all the available options

Examples

atmos validate stacks
atmos validate stacks --schemas-atmos-manifest schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

Flags

Flag	Description	Alias	Required
`--schemas-atmos-manifest`	Path to JSON Schema to validate Atmos stack manifests. Can be an absolute path or a path relative to the `base_path` setting in `atmos.yaml`		no

Validate Atmos Manifests using JSON Schema

Atmos can use the Atmos Manifest JSON Schema to validate Atmos stack manifests on the command line by executing the command atmos validate stacks.

For this to work, configure the following:

Add the Atmos Manifest JSON Schema to your repository, for example in stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

Configure the following section in the atmos.yaml CLI config file

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"

Execute the command atmos validate stacks
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 argument:
```
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
```

In case of any validation errors (invalid YAML syntax, Atmos manifest JSON Schema errors, invalid imports, etc.), you'll get an output from the command similar to the following:

atmos validate stacks

no matches found for the import 'globals/tenant1-globals-does-not-exist' in the
file 'catalog/invalid-yaml-and-schema/invalid-import-1.yaml'

invalid import in the file 'catalog/invalid-yaml-and-schema/invalid-import-2.yaml'
The file imports itself in 'catalog/invalid-yaml-and-schema/invalid-import-2'

invalid stack manifest 'catalog/invalid-yaml-and-schema/invalid-yaml-1.yaml'
yaml: line 15: found unknown directive name

invalid stack manifest 'catalog/invalid-yaml-and-schema/invalid-yaml-3.yaml'
yaml: line 13: did not find expected key

invalid stack manifest 'catalog/invalid-yaml-and-schema/invalid-yaml-5.yaml'
yaml: mapping values are not allowed in this context

invalid stack manifest 'catalog/invalid-yaml-and-schema/invalid-yaml-6.yaml'
yaml: line 2: block sequence entries are not allowed in this context

invalid stack manifest 'catalog/invalid-yaml-and-schema/invalid-yaml-7.yaml'
yaml: line 4: could not find expected ':'

Atmos manifest JSON Schema validation error in the
file 'catalog/invalid-yaml-and-schema/invalid-import-5.yaml':
{
  "valid": false,
  "errors": [
    {
      "keywordLocation": "",
      "absoluteKeywordLocation": "examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#",
      "instanceLocation": "",
      "error": "doesn't validate with examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#"
    },
    {
      "keywordLocation": "/properties/import/$ref",
      "absoluteKeywordLocation": "examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#/properties/import/$ref",
      "instanceLocation": "/import",
      "error": "doesn't validate with '/definitions/import'"
    },
    {
      "keywordLocation": "/properties/import/$ref/type",
      "absoluteKeywordLocation": "examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#/definitions/import/type",
      "instanceLocation": "/import",
      "error": "expected array, but got object"
    }
  ]
}

Atmos manifest JSON Schema validation error in the
file 'catalog/invalid-yaml-and-schema/invalid-schema-8.yaml':
{
  "valid": false,
  "errors": [
    {
      "keywordLocation": "",
      "absoluteKeywordLocation": "examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#",
      "instanceLocation": "",
      "error": "doesn't validate with examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#"
    },
    {
      "keywordLocation": "/properties/env/$ref",
      "absoluteKeywordLocation": "examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#/properties/env/$ref",
      "instanceLocation": "/env",
      "error": "doesn't validate with '/definitions/env'"
    },
    {
      "keywordLocation": "/properties/env/$ref/type",
      "absoluteKeywordLocation": "examples/tests/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#/definitions/env/type",
      "instanceLocation": "/env",
      "error": "expected object, but got array"
    }
  ]
}

atmos validate stacks --help

Usage​

atmos validate stacks

Examples​

Flags​

Validate Atmos Manifests using JSON Schema​

atmos validate stacks

Usage

Examples

Flags

Validate Atmos Manifests using JSON Schema