!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
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
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
:
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
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
):
components:
terraform:
tgw:
vars:
vpc_id: !terraform.output vpc {{ printf "net-%s-%s" .vars.environment .vars.stage }} vpc_id
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:
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
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:
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
withatmos describe affected
, Atmos requires access to all referenced remote states. If you operate with limited permissions (e.g., scoped todev
) 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.