Atmos YAML Functions

Atmos YAML Functions

Overview

YAML functions are the recommended way to add dynamic behavior to Atmos stack configurations. They use YAML explicit tags (the ! prefix) and operate on structured data after YAML parsing. They cannot break YAML syntax, are type-safe, and produce clear error messages.

All YAML functions support Go template expressions in their arguments. Atmos processes templates first, then executes the YAML functions.

Available YAML Functions

Supported Sections

YAML functions work in all Atmos stack manifest sections:

• vars, settings, env, metadata, command, component
• providers, overrides, backend, backend_type
• remote_state_backend, remote_state_backend_type

!terraform.state -- Fast State Backend Access (Recommended)

Reads outputs directly from the Terraform state backend without initialization. Supports S3, local, GCS, and azurerm backends. 10-100x faster than !terraform.output.

vars:
  # Two-parameter form: component + output (current stack)
  vpc_id: !terraform.state vpc vpc_id

  # Three-parameter form: component + stack + output
  vpc_id: !terraform.state vpc plat-ue2-prod vpc_id

  # Using Go templates for dynamic stack references
  vpc_id: !terraform.state vpc {{ .stack }} vpc_id

  # YQ expressions for complex outputs
  first_subnet: !terraform.state vpc .private_subnet_ids[0]
  db_host: !terraform.state config .config_map.username

  # Default values for unprovisioned components
  vpc_id: !terraform.state vpc .vpc_id // "default-vpc"

  # YQ string concatenation
  url: !terraform.state 'aurora-postgres .master_hostname | "jdbc:postgresql://" + . + ":5432"'

  # Bracket notation for keys with special characters
  key: !terraform.state security '.users["github-dependabot"].access_key_id'

Cold State and terraform plan --all

!terraform.state resolves configuration before Terraform plans a component. On a first aggregate plan, an upstream component may therefore have no state yet. Use a YQ // default for values that must exist at plan time, with a deterministic, provider-valid mock value:

vars:
  kms_key_arn: !terraform.state kms-key '.key_arn // "arn:aws:kms:us-east-2:000000000000:key/00000000-0000-0000-0000-000000000000"'

The deployed upstream output supersedes the fallback automatically. Dependency metadata controls deployment order; it does not create state before an aggregate plan.

Reusable Mocks vs. a One-Off // Default

The // default above is a per-expression fallback. For a producer component's mock outputs to be declared once and resolved consistently by every consumer, use the component's mocks: stack-config section together with --use-mocks (supported by atmos terraform plan and atmos describe component) instead of repeating a // default in every consuming expression:

components:
  terraform:
    vpc:
      mocks:
        vpc_id: vpc-mock1234
        private_subnet_ids: [subnet-a, subnet-b]
    app:
      vars:
        vpc_id: !terraform.state vpc vpc_id

atmos terraform plan app -s dev --use-mocks

By default (components.terraform.mocks.mode: fallback), mocks are fallbacks: the real value is used when it exists, and the producer's mocks: value is used only when the component is not provisioned or the output is missing. Credential, network, and backend errors still fail (the error hints at --use-mocks=always). The precedence is real value, then mock, then the caller's // default, then the original error. Map outputs are deep-merged: mocks sit under the real outputs, every value in real state wins, and a mock fills keys missing from a real map (real {a: 1} plus mock {a: 0, b: 2} gives {a: 1, b: 2}). Lists and scalars are never merged; a real list replaces the mock list. Terraform does not record null outputs in state, so in fallback mode a null output resolves to the mock; do not declare a mock for an output that can be null, or use always.

--use-mocks values (case-insensitive): absent, empty, or a false boolean (false, 0, f) is off; bare --use-mocks or a true boolean (true, 1, t) is on using the configured mode; --use-mocks=fallback or --use-mocks=always is on and overrides the configured mode for that run; any other value is an error. Attach the mode with =: --use-mocks always leaves always as a positional argument and Atmos errors. Only atmos terraform plan and atmos describe component accept the flag; other terraform subcommands reject it. ATMOS_USE_MOCKS accepts the same values for atmos terraform plan only; atmos describe component reads the flag, not the variable, and an exported ATMOS_USE_MOCKS makes apply, deploy, destroy, and other non-plan terraform subcommands fail until it is unset. Mode always is the hermetic behavior: lookups resolve from mocks: only and never initialize Terraform, authenticate, or read a backend for those lookups (a terraform plan still uses the planned component's own backend and credentials), and a missing mocks: map or output is an error (a // default still rescues it). The mode also comes from ATMOS_COMPONENTS_TERRAFORM_MOCKS_MODE; an invalid mode in atmos.yaml or that variable fails at config load. Unpinned projects default to fallback; projects whose atmos.yaml edition is pinned before 2026-10-01 default to always.

mocks: is Terraform-only and never templated or YAML-function-processed. Do not conflate this feature with the //-default idiom above; they're separate mechanisms, and a // default in the caller's expression is still honored even when the referenced component declares no mocks: section.