cloudposse/atmos/atmos-config

Atmos Root Configuration

Use this skill for the root mechanics of atmos.yaml: how Atmos finds config files, merges them, resolves project-relative paths, imports modular config, and routes section-specific work to the right skill. Do not use this skill as a catchall for every atmos.yaml section.

Configuration Discovery

Atmos searches for atmos.yaml in this order:

1. --config CLI flag or ATMOS_CLI_CONFIG_PATH.
2. Active profile selected by --profile or ATMOS_PROFILE.
3. Current working directory.
4. Git repository root.
5. Parent directory walk.
6. Home directory.
7. System directory.

When multiple configuration files apply, Atmos deep-merges them. More specific sources override broader defaults.

Root Layout

Use base_path for the project root that relative paths resolve from. Keep the root config small and point subsystem paths at their owning directories:

base_path: ""
 
stacks:
  base_path: stacks
  included_paths:
    - "**/*"
  excluded_paths:
    - "**/_defaults.yaml"
    - "catalog/**/*"
  name_template: "{{ .vars.stage }}"
 
components:
  terraform:
    base_path: components/terraform
 
workflows:
  base_path: stacks/workflows

For deeper path/layout guidance, load atmos-project-layout.

Modular Imports

Use import to split root config into focused files:

import:
  - atmos.d/stacks.yaml
  - atmos.d/components.yaml
  - atmos.d/auth.yaml
  - atmos.d/toolchain.yaml

Imported files are deep-merged into the active configuration. Keep imported files aligned with the subsystem they configure and load the subsystem skill before changing that section.

Routing

For a compact map of top-level sections, read references/sections-reference.md.

Guardrails

• Keep atmos-config examples minimal; detailed subsystem examples belong in their narrower skills.
• Before editing a subsystem section, load the owning skill from the routing table.
• Prefer atmos describe config or atmos describe component when verifying merge or path behavior.