From atmos
Documents atmos.yaml structure, discovery, merging, sections (stacks, components/terraform, workflows), env overrides for configuring Atmos IaC projects.
npx claudepluginhub cloudposse/atmos --plugin atmosThis skill uses the workspace's default tool permissions.
The `atmos.yaml` file is the central project configuration for Atmos. It defines how Atmos discovers stacks, where
Configures Atmos stacks with imports, inheritance, deep merging, vars, locals, settings, metadata, and overrides for Terraform/Helmfile components across environments.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
The atmos.yaml file is the central project configuration for Atmos. It defines how Atmos discovers stacks, where
components live, how templates are processed, and how every subsystem (auth, stores, workflows, toolchain, validation,
integrations) is configured. Every Atmos project needs at least one atmos.yaml.
Atmos searches for atmos.yaml in this order (first found wins):
--config CLI flag or ATMOS_CLI_CONFIG_PATH environment variable.--profile flag or ATMOS_PROFILE environment variable)../atmos.yaml).<repo-root>/atmos.yaml).~/.atmos/atmos.yaml)./usr/local/etc/atmos/atmos.yaml on Linux/macOS, %LOCALAPPDATA%/atmos/atmos.yaml on Windows).When multiple files are found, they are deep-merged with earlier sources taking precedence.
Most atmos.yaml settings can be overridden via environment variables using the ATMOS_ prefix:
ATMOS_BASE_PATH=/path/to/project
ATMOS_STACKS_BASE_PATH=stacks
ATMOS_COMPONENTS_TERRAFORM_BASE_PATH=components/terraform
ATMOS_WORKFLOWS_BASE_PATH=stacks/workflows
ATMOS_LOGS_LEVEL=Debug
The simplest atmos.yaml that works:
base_path: ""
stacks:
base_path: "stacks"
included_paths:
- "**/*"
excluded_paths:
- "**/_defaults.yaml"
- "catalog/**/*"
name_template: "{{ .vars.stage }}"
components:
terraform:
base_path: "components/terraform"
The atmos.yaml file supports these top-level sections. Each section is documented in detail in the
sections reference.
| Section | Purpose | Related Skill |
|---|---|---|
base_path | Root directory for all relative paths | -- |
stacks | Stack manifest discovery, naming, inheritance | atmos-stacks |
components | Component type paths and settings (Terraform, Helmfile, Packer, Ansible) | atmos-components |
import | Import other atmos.yaml files for modular configuration | -- |
version | Minimum/maximum Atmos version requirements | -- |
| Section | Purpose | Related Skill |
|---|---|---|
workflows | Workflow file discovery path | atmos-workflows |
commands | Custom CLI command definitions | atmos-custom-commands |
aliases | Command alias mappings | atmos-custom-commands |
templates | Go template and Gomplate processing settings | atmos-templates |
schemas | Validation schema base paths (JSON Schema, OPA, CUE) | atmos-schemas |
validate | Validation behavior (EditorConfig) | atmos-validation |
| Section | Purpose | Related Skill |
|---|---|---|
auth | Authentication providers, identities, keyring, integrations | atmos-auth |
stores | External key-value store backends | atmos-stores |
vendor | Vendoring base path and retry settings | atmos-vendoring |
toolchain | CLI tool version management, registries, aliases | atmos-toolchain |
devcontainer | Development container configurations | atmos-devcontainer |
| Section | Purpose | Related Skill |
|---|---|---|
settings | Global CLI behavior: terminal, telemetry, experimental features | -- |
integrations | Atlantis, GitHub Actions, Atmos Pro configuration | atmos-gitops |
logs | Log level and log file path | -- |
errors | Error format and Sentry integration | -- |
env | Global environment variables for all operations | -- |
profiles | Named configuration profiles base path | -- |
describe | describe command behavior settings | atmos-introspection |
docs | Documentation generation settings | -- |
metadata | Project metadata (name, version, tags) | -- |
base_path: ""
stacks:
base_path: "stacks"
included_paths:
- "orgs/**/*"
excluded_paths:
- "**/_defaults.yaml"
- "catalog/**/*"
- "mixins/**/*"
name_template: "{{ .vars.tenant }}-{{ .vars.environment }}-{{ .vars.stage }}"
components:
terraform:
base_path: "components/terraform"
command: "/usr/bin/terraform"
helmfile:
base_path: "components/helmfile"
workflows:
base_path: "stacks/workflows"
logs:
level: Info
base_path: ""
stacks:
base_path: "stacks"
included_paths:
- "deploy/**/*"
excluded_paths:
- "**/_defaults.yaml"
- "catalog/**/*"
name_template: "{{ .vars.stage }}"
components:
terraform:
base_path: "components/terraform"
auth:
providers:
company-sso:
kind: aws/iam-identity-center
region: us-east-1
start_url: https://company.awsapps.com/start
identities:
dev-admin:
kind: aws/permission-set
default: true
via:
provider: company-sso
principal:
name: AdminAccess
account:
name: development
stores:
ssm/dev:
type: aws-ssm-parameter-store
options:
region: us-east-1
identity: dev-admin
base_path: ""
stacks:
base_path: "stacks"
included_paths:
- "**/*"
excluded_paths:
- "**/_defaults.yaml"
name_template: "{{ .vars.stage }}"
components:
terraform:
base_path: "components/terraform"
schemas:
jsonschema:
base_path: "stacks/schemas/jsonschema"
opa:
base_path: "stacks/schemas/opa"
toolchain:
registries:
- type: aqua
ref: "v4.332.0"
settings:
terminal:
pager: false
syntax_highlighting:
enabled: true
# atmos.yaml
import:
- atmos.d/stacks.yaml
- atmos.d/auth.yaml
- atmos.d/stores.yaml
base_path: ""
components:
terraform:
base_path: "components/terraform"
Imported files are deep-merged into the main configuration, allowing modular organization of large configs.
# profiles/developer/atmos.yaml
auth:
providers:
company-sso:
session:
duration: 8h
# profiles/ci/atmos.yaml
auth:
providers:
github-oidc:
kind: github/oidc
region: us-east-1
Activate with --profile developer or ATMOS_PROFILE=ci.
The components.terraform section has extensive subsystem configuration:
components:
terraform:
base_path: "components/terraform"
command: "terraform"
apply_auto_approve: false
deploy_run_init: true
init_run_reconfigure: true
auto_generate_backend_file: true
# Backend defaults applied to all Terraform components
backend_type: s3
backend:
s3:
encrypt: true
bucket: "acme-terraform-state"
dynamodb_table: "acme-terraform-state-lock"
region: "us-east-1"
key: "terraform.tfstate"
acl: "bucket-owner-full-control"
workspace_key_prefix: "terraform"
# Shell configuration for `atmos terraform shell`
shell:
shell: "/bin/bash"
For the complete Terraform configuration reference, see the atmos-terraform skill.
Global CLI behavior and feature settings:
settings:
# Terminal/UI settings
terminal:
pager: false
max_width: 120
colors: true
unicode: true
syntax_highlighting:
enabled: true
theme: dracula
masking:
enabled: true
# Telemetry
telemetry:
enabled: true
# Experimental features
experimental:
enabled: false
Pin the minimum Atmos version required for the project:
version:
check:
enabled: true
constraints: ">= 1.100.0"
# Show resolved configuration
atmos describe config
# Show where atmos.yaml was loaded from
ATMOS_LOGS_LEVEL=Debug atmos version
# Validate the configuration
atmos validate stacks
atmos.yaml (or a set of imported files) configures the entire project.ATMOS_ environment variable.import to split large configs across files.