more terraform command options that aren't specifically a stack or every single stack

--error-mode

atmos terraform apply --affected --tags production

!terraform.state

'{{ atmos.Resolve (printf `!terraform.state cloudposse-kms-key hello-world-%s ".key_arn // ""default"""` (regexReplaceAll "[0-9]+$" .vars.deployment_requirements.stage "x")) }}'

Here's what that expression does, step by step (I verified the semantics against internal/exec/template_funcs.go:61, internal/exec/yaml_func_terraform_state.go, and the new argument parser in pkg/function/parser/parser.go):

  1. It's a Go template expression, evaluated while Atmos renders templates during stack processing — i.e., before YAML functions are normally processed, with the current component/stack as context.
  2. Innermost step — regexReplaceAll "[0-9]+$" .vars.deployment_requirements.stage "x": takes the stage name from vars.deployment_requirements.stage and replaces a trailing run of digits with the literal letter x. For example, prod-3 → prod-x, dev12 → devx; a stage with no trailing digits (e.g. dev) passes through unchanged. So all numbered instances of a stage collapse to one -x name.
  3. printf builds a YAML-function call as a string, injecting that transformed stage into the format hello-world-%s. The result is:
  !terraform.state cloudposse-kms-key hello-world-prod-x ".key_arn // ""default""" (using the prod-3 example).
  4. The doubled quotes are the escaping convention for quoted YAML-function arguments (a "" inside a "…"-quoted argument is a literal "). After unquoting, the third argument is the YQ expression .key_arn // "default". The final """ is an escaped quote plus the closing quote.
  5. atmos.Resolve evaluates that string as the !terraform.state YAML function at template-render time. This is the reason for the whole construction: a bare !terraform.state YAML tag owns the entire scalar and can't have a templated stack name spliced into it, whereas atmos.Resolve lets you compose the function call from template data.
  6. !terraform.state reads the Terraform state directly from the configured backend (no terraform init/terraform output subprocess) for component cloudposse-kms-key in stack hello-world-<stage-with-x>, then applies the YQ expression to the state outputs.
  7. The YQ // operator provides a fallback: it returns the key_arn output, or the string "default" if key_arn is null or missing.
  8. The fallback also covers the never-provisioned case: because the expression contains //, Atmos treats "state not provisioned" and "output not found" as recoverable — it evaluates the YQ default against an empty document and returns "default" instead of failing the whole stack processing.

  Net effect: "Give me the KMS key ARN from the cloudposse-kms-key component in the hello-world-<stage> stack — where any numeric stage suffix is normalized to x (so e.g. prod-1, prod-2, prod-3 all share hello-world-prod-x's key) — and if that component isn't provisioned or has no key_arn output, use the string default instead."

  One caveat worth knowing: the digit-run replacement maps prod-123 to prod-x (the entire run of digits is replaced by a single x), and the literal string "default" is a placeholder value, not a real ARN — so downstream consumers presumably treat default as a sentinel (e.g., "use the AWS-managed key").

distinction between direct Terraform state references and state references
  used inside generated JSON.

  A direct value like this works as expected:

  kms_key_id: !terraform.state cloudposse-kms-key ...

  That value is consumed directly as a Terraform input, so Atmos resolves it during stack
  processing.

  The external-secrets KMS ARN follows a different path:

  Terraform variable
  → IAM policy statement
  → JSON serialization with toJson
  → aws_iam_policy

  Because the value is embedded inside a templated policy structure, the !terraform.state
  expression can survive into the later template/JSON-rendering phase instead of being fully
  evaluated first. Terraform then receives malformed JSON and reports errors such as:

  invalid character '.' after array element

  Wrapping the expression with atmos.Resolve forces Atmos to resolve the remote state value before
  the policy is serialized:

  external_secrets_kms_key_arn: '{{ atmos.Resolve (printf `!terraform.state ...`) }}'

  That produces a concrete ARN before toJson builds the IAM policy.

  General rule: direct !terraform.state references are appropriate for ordinary Terraform
  variables. When a state-derived value is interpolated into a generated JSON document, policy, or
  another nested template, resolve it explicitly first with atmos.Resolve.

foo: !terraform.state {
  component: cloudposse-kms-key,
  stack: 'hello-world-{{ regexReplaceAll "[0-9]+$" .vars.deployment_requirements.stage "x" }}',
  output: key_arn,
  default: default,
}

| toJson

| toJson

--include-dependents=depth

--include-dependencies=depth

atmos terraform apply --all --labels=layer:$app-dev1 --include-dependencies=3 --use-version=2807

✗ Failed to resolve Terraform component instances

   Terraform preflight failed

   Error: failed to execute describe stacks: failed to read Terraform state for component  uds-vpc  in stack $stack...in YAML function:
   !terraform.state uds-vpc...
...
failed to get object from S3:....$bucket" because no resource-based policy allows the s3:ListBucket
  action

    Terraform component instances could not be resolved before Terraform started.

--labels=layer:$app-dev1 --include-dependencies

atmos.Resolve

$app-dev1

vars:
  workflow:
    app: $app
    layer: slot
    environment: dev
    slot: 1
    is_active: true
    parents:
      - uds-dev1
      - $app-devx

---
$app-devx

vars:
  workflow:
    app: $app
    layer: environment
    environment: dev
    parents:
      - $app-$account

---
$app-$account

vars:
  workflow:
    app: $app
    layer: account
    account: $account
    parents: []

atmos.Resovle

Pushed as cbddda4e2e — Zack's report exposed two real scope leaks, both now fixed on PR #2807. Here's the full picture to relay:

Zack's expectation is correct — and he found two genuine holes

Hole 1 — stack-granularity evaluation (his "off by one" instinct was right). The closure decided which stacks to evaluate, then evaluated every component in those stack files — so a component that merely shares a stack file with an in-closure prerequisite got its !terraform.state resolved, and its cross-account S3 read failed auth, even though it was never selected. That matches his evidence exactly: atmos showed the other account's bucket name because it was faithfully evaluating a component it should never have touched. Fixed: every resolved describe pass is now narrowed to the closure's own components within each stack, with a regression test proving a "poison" component sharing a stack with closure members is never evaluated.

Hole 2 — templated selector values. If metadata.labels values are templates (likely, given his labeling strategy), the lightweight pass couldn't decide them, so it conservatively treated every such component as a closure seed — quietly inflating the closure toward the whole repo, which explains functions resolving in stacks "not referenced or imported" by anything he deployed. Fixed: since the purity contract guarantees selectors are at most simple templates over the stack context, the lightweight matcher now renders them directly (sprig functions, custom delimiters honored); a value like layer: "{{ .<http://vars.app|vars.app> }}-dev1" now matches exactly. Only genuinely unresolvable values still widen scope — conservatively, never excluding.

cbddda4e2e

atmos build

--all --labels

[atmos] git log --oneline | head -n 1                                                                                                                                                                                                          cbddda4e2│15:57:55
cbddda4e2 fix: evaluate only the closure's own components, and resolve templated selectors in the lightweight phase

--stack

dependencies:
        components:
          - name: cloudposse-kms-key
            stack: "$app-{{ .vars.environment_stage }}"
          - name: uds-vpc
            stack: '{{ printf "$app-%s" .vars.deployment_requirements.stage }}'
          - name: uds-eks
            stack: '{{ printf "$app-%s" .vars.deployment_requirements.stage }}'
          - name: uds-bastion
            stack: '{{ printf "$app-%s" .vars.deployment_requirements.stage }}'

atmos describe config

stacks.base_path.included_paths

atmos profile

--use-version=

atmos --profile

atmos.yaml

stacks.included_paths