cloudposse/docs/atmos-functions

Cross-Component Dependencies with Atmos Functions

Preferred approach: Atmos Functions - Use Atmos template functions in stack YAML to pass values between components at plan/apply time. This avoids Terraform remote state lookups entirely.

!terraform.state Syntax

Two-parameter form (current stack):

!terraform.state <component> <output>

Three-parameter form (specific stack):

!terraform.state <component> <stack> <output>

Examples

components:
  terraform:
    my-component:
      vars:
        # Current stack lookups (component output)
        vpc_id: !terraform.state vpc vpc_id
        subnet_ids: !terraform.state vpc private_subnet_ids
 
        # Cross-stack lookup (component stack output)
        grafana_role_arn: !terraform.state grafana core-use2-auto workspace_iam_role_arn
 
        # Nested output with YQ expression
        role_arn: !terraform.state iam-role/my-role plat-use2-dev .role.arn

!terraform.output Alternative

There's also !terraform.output which has the same syntax but different behavior:

# Same syntax as !terraform.state
vpc_id: !terraform.output vpc vpc_id

Key differences:

Always prefer `!terraform.state` - it's significantly faster because it reads the state file directly from S3 without running Terraform commands.

Best Practices

• Use `!terraform.state` over `!terraform.output` - Direct S3 access is much faster than running Terraform.
• Define lookups in catalog defaults - Put !terraform.state expressions in

stacks/catalog/<component>/defaults.yaml rather than in stack files. The function automatically resolves based on the current stack context.

• Use current-stack lookups when possible - Omit the stack parameter to look up components in the same stack, making

configs more portable.

• Cross-stack lookups for shared resources - Use the three-parameter form when referencing centralized resources

(e.g., Grafana in core-auto from plat accounts).

Legacy Approach (Being Phased Out)

Some older components still use Cloud Posse's remote-state Terraform module with remote-state.tf files. This pattern is being phased out in favor of Atmos functions. The tfstate backend is in the core-auto account.

When you encounter remote-state.tf files, prefer converting them to !terraform.state expressions in the catalog.