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

# Use the default (embedded) JSON Schema
atmos validate stacks

# Point to the JSON Schema on the local filesystem
atmos validate stacks --schemas-atmos-manifest schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

# Point to the remote JSON Schema
atmos validate stacks --schemas-atmos-manifest https://atmos.tools/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 a URL, an absolute path, or a path relative to the base_path setting in atmos.yaml		no

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:

• 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"
      # 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

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": "tests/fixtures/scenarios/complete/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#",
      "instanceLocation": "",
      "error": "doesn't validate with tests/fixtures/scenarios/complete/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#"
    },
    {
      "keywordLocation": "/properties/import/$ref",
      "absoluteKeywordLocation": "tests/fixtures/scenarios/complete/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": "tests/fixtures/scenarios/complete/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": "tests/fixtures/scenarios/complete/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#",
      "instanceLocation": "",
      "error": "doesn't validate with tests/fixtures/scenarios/complete/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#"
    },
    {
      "keywordLocation": "/properties/env/$ref",
      "absoluteKeywordLocation": "tests/fixtures/scenarios/complete/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": "tests/fixtures/scenarios/complete/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json#/definitions/env/type",
      "instanceLocation": "/env",
      "error": "expected object, but got array"
    }
  ]
}