Atmos Stacks

Atmos Stack Configuration

Stacks are YAML configuration files that define which components to deploy, with what settings, and how they relate to each other. They separate configuration from infrastructure code, enabling the same Terraform root modules to be deployed across many environments with different settings.

What Stacks Are

A stack manifest is a YAML file that declares components and their configuration for a specific combination of organization, tenant, account, region, and stage. Atmos discovers stack manifests based on included_paths and excluded_paths in atmos.yaml, then deep-merges all imported configurations to produce the final resolved state for each component.

Stacks are not Terraform workspaces, although Atmos derives workspace names from stack names. A single stack manifest can configure multiple components, and a single component can appear across many stacks with different variable values.

Related Skills

Stack Discovery

Atmos discovers stack manifests based on included_paths and excluded_paths configured in the stacks section of atmos.yaml. For root config discovery and routing, see the atmos-config skill; for path layout and base_path behavior, see atmos-project-layout.

Stack Name Precedence

Atmos resolves the stack name using this priority (highest first):

1. name field in the stack manifest (explicit override).
2. name_template in atmos.yaml (Go template).
3. Legacy name_pattern in atmos.yaml (migration-only; recommend name_template or explicit name).
4. File basename (e.g., prod.yaml becomes prod).

Stack Manifest Structure

A stack manifest can contain the following top-level sections:

# Optional: explicit stack name override
name: "plat-ue2-prod"

# Import other configurations
import:
  - catalog/vpc/defaults
  - mixins/region/us-east-2
  - orgs/acme/plat/prod/_defaults
  # Remote imports are supported, but they import stack config only:
  # - github://acme/config/main/stacks/catalog/vpc.yaml

# Global-scope sections (apply to all components)
vars: {}
locals: {}
env: {}
settings: {}
hooks: {}
overrides: {}

# Component-type scope (apply to all components of that type)
terraform:
  vars: {}
  env: {}
  settings: {}
  hooks: {}
  backend_type: s3
  backend: {}
  providers: {}
  command: terraform
  overrides: {}

helmfile:
  vars: {}
  env: {}
  settings: {}
  hooks: {}
  command: helmfile
  overrides: {}

# Component definitions
components:
  terraform:
    vpc:
      metadata: {}
      vars: {}
      env: {}
      settings: {}
      hooks: {}
      backend_type: s3
      backend: {}
      providers: {}
      command: terraform
      auth: {}
  helmfile:
    echo-server:
      vars: {}
      env: {}
      settings: {}

Configuration Sections Reference

vars

Variables passed as inputs to Terraform, Helmfile, or Packer components. Defined at global, component-type, or component level. Deep-merged across all levels with component-level values taking precedence.

vars:
  environment: prod
  region: us-east-1
  tags:
    Environment: Production
    ManagedBy: Atmos

Maps are recursively merged; lists are replaced (not appended).

locals

File-scoped temporary variables for reducing repetition within a single YAML file. Locals do NOT inherit across file imports. They can reference each other using {{ .locals.name }} syntax with automatic dependency resolution.

locals:
  namespace: acme
  name_prefix: "{{ .locals.namespace }}-{{ .vars.stage }}"

components:
  terraform:
    vpc:
      vars:
        name: "{{ .locals.name_prefix }}-vpc"

Locals can also access settings, vars, and env defined in the same file using {{ .settings.key }}, {{ .vars.key }}, and {{ .env.KEY }}.

env

Environment variables set when executing components. Simple key-value pairs merged shallowly across levels.

env:
  AWS_PROFILE: acme-prod
  TF_IN_AUTOMATION: "true"

settings

Integration metadata and configuration not passed to Terraform. Used for Atlantis, validation, and other Atmos integrations.

settings:
  validation:
    check-cidr:
      schema_type: jsonschema
      schema_path: schemas/vpc.json
dependencies:
  components:
    - component: vpc
    - component: dns-zone
      stack: plat-ue2-prod
    - kind: file
      path: configs/service.yaml

metadata

Component-only section that controls Atmos behavior for that component. Cannot be used at global or component-type level.

components:
  terraform:
    vpc:
      metadata:
        component: vpc           # Terraform root module path
        inherits:
          - vpc/defaults         # Inheritance chain
        type: abstract           # abstract or real (default)
        enabled: true            # Enable/disable component
        locked: false            # Prevent modifications
        terraform_workspace: "custom-ws"
        custom:
          owner: platform-team

hooks

Lifecycle event handlers that execute actions at specific points (e.g., after terraform apply).

hooks:
  store-outputs:
    events:
      - after-terraform-apply
    command: store
    name: prod/ssm
    outputs:
      vpc_id: .vpc_id

command

Override the executable for a component type or specific component. Useful for OpenTofu, custom wrappers, or version-pinned binaries.

terraform:
  command: tofu

flags

Default values for terraform CLI execution flags (lock_timeout, lock, parallelism, refresh, compact_warnings). Settable in atmos.yaml (components.terraform.flags), at the stack level (root-level terraform: block), and per component — merged field-by-field, lowest to highest precedence. An explicit CLI-typed flag (-- -lock-timeout=30s) always wins over all three. Terraform-only; not every flag applies to every subcommand.

terraform:
  flags:
    lock_timeout: "5m"

components:
  terraform:
    vpc:
      flags:
        parallelism: 4

backend

Terraform backend configuration. Atmos generates backend.tf.json automatically.

terraform:
  backend_type: s3
  backend:
    s3:
      bucket: acme-ue1-root-tfstate
      region: us-east-1
      encrypt: true
      use_lockfile: true

providers

Terraform provider configuration. Atmos generates providers_override.tf.json automatically.

terraform:
  providers:
    aws:
      region: us-east-1
      assume_role:
        role_arn: "arn:aws:iam::{{ .vars.account_id }}:role/TerraformRole"

auth

Authentication configuration for cloud providers. Primarily defined in atmos.yaml but can be referenced at component level.

components:
  terraform:
    vpc:
      auth:
        identity: prod-admin

overrides

Scoped overrides that apply only to components defined in the current manifest and its imports (not to all components in the top-level stack). This is different from regular vars/env/settings which affect all components.

overrides:
  env:
    TEST_ENV_VAR: "overridden-value"
  vars:
    custom_tag: override
  settings:
    validation:
      check-cidr:
        schema_path: schemas/vpc-override.json