Skip to main content

!terraform.output

The !terraform.output YAML function allows reading the outputs (remote state) of components directly in Atmos stack manifests.

Usage

The !terraform.output function can be called with either two or three parameters:

  # Get the `output` of the `component` in the current stack
!terraform.output <component> <output>

# Get the `output` of the `component` in the provided stack
!terraform.output <component> <stack> <output>

Arguments

component
Atmos component name
stack
(Optional) Atmos stack name
output
Terraform output
tip

You can use Atmos Stack Manifest Templating in the !terraform.output YAML function expressions. Atmos processes the templates first, and then executes the !terraform.output function, allowing you to provide the parameters to the function dynamically.

Using YQ Expressions to retrieve items from complex output types

To retrieve items from complex output types such as maps and lists, or do any kind of filtering or querying, you can utilize YQ expressions.

For example:

  • Retrieve the first item from a list
subnet_id1: !terraform.output vpc .private_subnet_ids[0]
  • Read a key from a map
username: !terraform.output config .config_map.username

For more details, review the following docs:

Examples

stack.yaml

components:
terraform:
my_lambda_component:
vars:
vpc_config:
# Output of type string
security_group_id: !terraform.output security-group/lambda id
security_group_id2: !terraform.output security-group/lambda2 {{ .stack }} id
security_group_id3: !terraform.output security-group/lambda3 {{ .atmos_stack }} id
# Output of type list
subnet_ids: !terraform.output vpc private_subnet_ids
# Use a YQ expression to get an item from the list
subnet_id1: !terraform.output vpc .private_subnet_ids[0]
# Output of type map
config_map: !terraform.output config {{ .stack }} config_map
# Use a YQ expression to get a value from the map
username: !terraform.output config .config_map.username

Specifying Atmos stack

If you call the !temolate function with three parameters, you need to specify the stack as the second argument.

There are multiple ways you can specify the Atmos stack parameter in the !terraform.output function.

Hardcoded Stack Name

Use it if you want to get an output from a component from a different (well-known and static) stack. For example, you have a tgw component in a stack plat-ue2-dev that requires the vpc_id output from the vpc component from the stack plat-ue2-prod:

plat-ue2-dev
  components:
terraform:
tgw:
vars:
vpc_id: !terraform.output vpc plat-ue2-prod vpc_id

Reference the Current Stack Name

Use the .stack (or .atmos_stack) template identifier to specify the same stack as the current component is in (for which the !terraform.output function is executed):

  !terraform.output <component> {{ .stack }} <output>
!terraform.output <component> {{ .atmos_stack }} <output>

For example, you have a tgw component that requires the vpc_id output from the vpc component in the same stack:

  components:
terraform:
tgw:
vars:
vpc_id: !terraform.output vpc {{ .stack }} vpc_id
note

Using the .stack or .atmos_stack template identifiers to specify the stack is the same as calling the !terraform.output function with two parameters without specifying the current stack, but without using Go templates. If you need to get an output of a component in the current stack, using the !terraform.output function with two parameters is preferred because it has a simpler syntax and executes faster.

Use a Format Function

Use the printf template function to construct stack names using static strings and dynamic identifiers. This is convenient when you want to override some identifiers in the stack name:

  !terraform.output <component> {{ printf "%s-%s-%s" .vars.tenant .vars.environment .vars.stage }} <output>

!terraform.output <component> {{ printf "plat-%s-prod" .vars.environment }} <output>

!terraform.output <component> {{ printf "%s-%s-%s" .settings.context.tenant .settings.context.region .settings.context.account }} <output>
<component
Placeholder for an actual component name (e.g. vpc)
<output>
Placeholder for an actual Terraform output (e.g. subnet_ids)

For example, you have a tgw component deployed in the stack plat-ue2-dev. The tgw component requires the vpc_id output from the vpc component from the same environment (ue2) and same stage (dev), but from a different tenant net (instead of plat):

plat-ue2-dev
  components:
terraform:
tgw:
vars:
vpc_id: !terraform.output vpc {{ printf "net-%s-%s" .vars.environment .vars.stage }} vpc_id
Important

By using the printf "%s-%s-%s" function, you are constructing stack names using the stack context variables/identifiers.

For more information on Atmos stack names and how to define them, refer to stacks.name_pattern and stacks.name_template sections in atmos.yaml CLI config file

Caching the result of !terraform.output function

Atmos caches (in memory) the results of !terraform.output function.

The cache is per Atmos CLI command execution, e.g., each new execution of a command like atmos terraform plan, atmos terraform apply or atmos describe component will create and use a new memory cache, which involves re-invoking terraform outputs after reinitialization.

If you define the function in stack manifests for the same component in a stack more than once, the first call will produce the result and cache it, and all the consecutive calls will just use the cached data. This is useful when you use the !terraform.output function for the same component in a stack in multiple places in Atmos stack manifests. It will speed up the function execution and stack processing.

For example:

components:
terraform:
test2:
vars:
tags:
test: !terraform.output test id
test2: !terraform.output test id
test3: !terraform.output test {{ .stack }} id

In the example, the test2 Atmos component uses the outputs (remote state) of the test Atmos component from the same stack. The YAML function !terraform.output is executed three times (once for each tag).

After the first execution, Atmos caches the result in memory, and reuses it in the next two calls to the function. The caching makes the stack processing much faster. In a production environment where many components are used, the speedup can be significant.

Using !terraform.output with static remote state backend

Atmos supports brownfield configuration by using the remote state of type static.

For example:

stack.yaml

components:
terraform:
# Component `static-backend` is configured with the remote state backend of type `static`
static-backend:
remote_state_backend_type: static
remote_state_backend:
static:
region: "us-west-2"
cluster_name: "production-cluster"
vpc_cidr: "10.0.0.0/16"
database:
type: "postgresql"
version: "12.7"
storage_gb: 100
allowed_ips:
- "192.168.1.0/24"
- "10.1.0.0/16"
tags:
Environment: "production"
Owner: "infra-team"

eks-cluster:
vars:
region: !terraform.output static-backend region
cluster_name: !terraform.output static-backend cluster_name
vpc_cidr: !terraform.output static-backend vpc_cidr
db_type: !terraform.output static-backend database.type
db_storage: !terraform.output static-backend database.storage_gb
allowed_ips: !terraform.output static-backend allowed_ips
tags: !terraform.output static-backend tags

When the functions are executed, Atmos detects that the static-backend component has the static remote state configured, and instead of executing terraform output, it just returns the static values from the remote_state_backend.static section.

Executing the command atmos describe component eks-cluster -s <stack> produces the following result:

atmos describe component eks-cluster -s <stack>

vars:
region: us-west-2
cluster_name: production-cluster
vpc_cidr: 10.0.0.0/16
db_type: postgresql
db_storage: 100
allowed_ips:
- 192.168.1.0/24
- 10.1.0.0/16
tags:
Environment: production
Owner: infra-team

Considerations

  • Using !terraform.output with secrets can expose sensitive data to standard output (stdout) in any commands that describe stacks or components.

  • When using !terraform.output with atmos describe affected, Atmos requires access to all referenced remote states. If you operate with limited permissions (e.g., scoped to dev) and reference production stacks, the command will fail.

  • Overusing the function within a stack to reference multiple components can significantly impact performance.

  • Be mindful of disaster recovery (DR) implications when using it across regions.

  • Consider cold-start scenarios: if the dependent component has not yet been provisioned, terraform output will fail.