atmos.Component

The atmos.Component template function allows reading any Atmos section or any attribute from a section for an Atmos component in a stack, and use it in Go templates in Atmos component configurations.

Usage

  {{ (atmos.Component "<component>" "<stack>").<section>.<attribute> }}

Arguments

component

Atmos component name

stack

Atmos stack name

section

Atmos section name. Any section returned by the CLI command atmos describe component can be used. A special outputs section is also supported to get the outputs (remote state) of Terraform/OpenTofu components.

outputs

Using the outputs section in the atmos.Component command is an convenient way to read the outputs (remote state) of a component in a stack directly in Atmos stack manifests. It is an alternative to using the remote-state module and configuring Terraform/OpenTofu components to use the remote-state module as described in Component Remote State

attribute

Attribute name (field) from the section. attribute is optional, you can use the section itself if it's a simple type (e.g. string). Any number of attributes can be chained using the dot (.) notation. For example, if the first two attributes are maps, you can chain them and get a field from the last map:

{{ (atmos.Component "<component>" "<stack>").<section>.<attribute1>.<attribute2>.<field1> }}

Specifying Atmos stack

There are multiple ways you can specify the Atmos stack parameter in the atmos.Component function.

The stack argument is the second argument of the atmos.Component function, and it can be specified in a few different ways:

Hardcoded Stack Name

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: '{{ (atmos.Component "vpc" "plat-ue2-prod").outputs.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 atmos.Component function is executed):

  {{ (atmos.Component "<component>" .stack).<section>.<attribute> }}
  {{ (atmos.Component "<component>" .atmos_stack).<section>.<attribute> }}

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: '{{ (atmos.Component "vpc" .stack).outputs.vpc_id }}'

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:

  {{ (atmos.Component "<component>" (printf "%s-%s-%s" .vars.tenant .vars.environment .vars.stage)).<section>.<attribute> }}

  {{ (atmos.Component "<component>" (printf "plat-%s-prod" .vars.environment)).<section>.<attribute> }}

  {{ (atmos.Component "<component>" (printf "%s-%s-%s" .settings.context.tenant .settings.context.region .settings.context.account)).<section>.<attribute> }}

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: '{{ (atmos.Component "vpc" (printf "net-%s-%s" .vars.environment .vars.stage)).outputs.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

Handling Outputs Containing Maps or Lists

You can use the atmos.Component function to read complex outputs (remote state) from Terraform/OpenTofu components, and use those in your stack manifests. To effectively use atmos.Component outputs in stack configurations, it’s important to understand the relationship between YAML and JSON. YAML is a superset of JSON, meaning you can embed JSON directly inside YAML, but the reverse is not true.

This means:

1. The output of a template function must be valid YAML (including the relative whitespace based on its current position) or JSON to be parsed correctly.
2. Simple types like strings are straightforward — they can be returned as-is.
3. Complex types like lists or maps must be serialized into JSON to ensure compatibility.

note

There are a few ways to handle the complex output types (maps and lists) from the atmos.Component function:

• Using the !template Atmos YAML function and the toRawJson or toJson template functions (this is the recommended way)
• Adjusting the template delimiters in atmos.yaml and using the toRawJson or toJson template functions

Using the !template Atmos YAML Function and toRawJson or toJson template functions

You can use the !template Atmos YAML function to handle the outputs containing maps or lists.

The !template YAML function correctly handles the JSON returned from the toRawJson or toJson functions and converts the result into the list or map YAML types. The final result of type list or map can be sent directly to the corresponding Terraform/OpenTofu component without modifying the types of the input variables.

stack.yaml

components:
  terraform:
    my_lambda_component:
      vars:
        vpc_config:
          security_group_ids: ['{{ (atmos.Component "security-group/lambda" .stack).outputs.id }}']

          # Output of type list from the `atmos.Component` template function
          subnet_ids: !template '{{ toJson (atmos.Component "vpc" .stack).outputs.private_subnet_ids }}'

          # Output of type map from the `atmos.Component` template function
          config_map: !template '{{ toJson (atmos.Component "config" .stack).outputs.config_map }}'

Adjusting the template delimiters in atmos.yaml and using the toRawJson or toJson template functions

First, we need to adjust the delimiters in atmos.yaml, to avoid issues with YAML parsing:

atmos.yaml

templates:
  settings:
    # Note the deliberate use of single quotes around the braces to avoid YAML parsing issues
    delimiters: ["'{{", "}}'"]

Detailed Explanation

In YAML, the default {{ and }} delimiters used for templating can conflict with YAML’s syntax rules, leading to parsing errors. For example, YAML interprets unquoted braces as JSON maps, which can cause YAML parsing to fail.

1. YAML Parsing Phase First, the file is parsed as YAML to extract its structure, such as imports. At this stage, the file must be valid YAML for Atmos to proceed. If the template expressions inside {{ ... }} are not properly handled, they can break the YAML syntax, leading to parsing errors.

2. Go Template Processing Phase: After successfully parsing the YAML structure, Atmos treats the file as a Go template and processes the content. Here’s what happens:

   • Everything between the delimiters ({{ ... }}) is replaced by the result of the template function or expression.
   • The output of this replacement must also be valid YAML so the file can remain usable for the next steps (e.g., Terraform processing).

3. How Adjusted Delimiters Work: By configuring delimiters as ["'{{", "}}'"] in atmos.yaml, you ensure that:

   • During the YAML Parsing Phase, the single quotes (') around the template expressions make them valid YAML strings, allowing the file to pass YAML validation.
   • During the Go Template Processing Phase, Atmos processes the content within '{{ and }}' and replaces it with the evaluated result.

Then we can use the toRawJson or toJson functions to serialize complex types into JSON:

  components:
  terraform:
    my_lambda_component:
      vars:
        vpc_config:
          security_group_ids: ['{{ (atmos.Component "security-group/lambda" .stack).outputs.id }}']
          subnet_ids: '{{ toRawJson ((atmos.Component "vpc" .stack).outputs.private_subnet_ids) }}'

The results of the toRawJson function are serialized into JSON, which can be safely embedded in the YAML stack configuration. The single quotes around the braces in the delimiters setting ensure that the JSON is not parsed as YAML, but then processed as a template function which removes the single quotes and replaces it with the JSON string.

Examples

The following configurations show different ways of using the atmos.Component template function to read values from different Atmos sections directly in Atmos stack manifests, including the outputs of other (already provisioned) components.

# Global `settings` section
# It will be added and deep-merged to the `settings` section of all components
settings:
  test: true

components:
  terraform:
    test:
      metadata:
        # Point to the Terraform/OpenTofu component
        component: "test"
      vars:
        name: "test"

    test1:
      metadata:
        # Point to the Terraform/OpenTofu component
        component: "test1"
      vars:
        name: "test1"

    test2:
      metadata:
        # Point to the Terraform/OpenTofu component
        component: "test2"
      vars:
        name: "test2"
        # Use the `atmos.Component` function to get the outputs of the Atmos component `test1`
        # The `test1` component must be already provisioned and its outputs stored in the Terraform/OpenTofu state
        # Atmos will execute `terraform output` on the `test1` component in the same stack to read its outputs
        test1_id: '{{ (atmos.Component "test1" .stack).outputs.test1_id }}'
        tags:
          # Get the `settings.test` field from the `test` component in the same stack
          test: '{{ (atmos.Component "test" .stack).settings.test }}'
          # Get the `metadata.component` field from the `test` component in the same stack
          test_terraform_component: '{{ (atmos.Component "test" .stack).metadata.component }}'
          # Get the `vars.name` field from the `test1` component in the same stack
          test1_name: '{{ (atmos.Component "test1" .stack).vars.name }}'

Caching the result of atmos.Component function

Atmos caches (in memory) the results of atmos.Component template function execution. If you call the function 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 atmos.Component 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: '{{ (atmos.Component "test" .stack).outputs.id }}'
          test2: '{{ (atmos.Component "test" .stack).outputs.id }}'
          test3: '{{ (atmos.Component "test" .stack).outputs.id }}'

In the example, the test2 Atmos component uses the outputs (remote state) of the test Atmos component from the same stack. The template function {{ atmos.Component "test" .stack }} is executed three times (once for each tag).

After the first execution, Atmos caches the result in memory (all the component sections, including the outputs), and reuses it in the next two calls to the function. The caching makes the stack processing about three times faster in this particular example. In a production environment where many components are used, the speedup can be even more significant.

Using atmos.Component 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: '{{ (atmos.Component "static-backend" .stack).outputs.region }}'
        cluster_name: '{{ (atmos.Component "static-backend" .stack).outputs.cluster_name }}'
        vpc_cidr: '{{ (atmos.Component "static-backend" .stack).outputs.vpc_cidr }}'
        db_type: '{{ (atmos.Component "static-backend" .stack).outputs.database.type }}'
        db_storage: '{{ (atmos.Component "static-backend" .stack).outputs.database.storage_gb }}'
        # Use the `!template` YAML function to correctly handle the outputs of types map and list
        allowed_ips: !template '{{ (atmos.Component "static-backend" .stack).outputs.allowed_ips }}'
        tags: !template '{{ (atmos.Component "static-backend" .stack).outputs.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