Skip to main content

Atmos YAML Functions

Advanced

Atmos YAML Functions are a crucial part of Atmos stack manifests. They allow you to manipulate data and perform operations on the data to customize the stack configurations.

Atmos YAML functions are based on YAML Explicit typing and user-defined Explicit Tags (local data types). Explicit tags are denoted by the exclamation point ("!") symbol. Atmos detects the tags in the stack manifests and executes the corresponding functions.

info

YAML supports three types of data: core, defined, and user-defined.

  • Core types: Universally supported, including floats, integers, strings, lists, and maps.
  • Defined types: Advanced types like binary data, specified in the YAML standard but not always supported.
  • User-defined types: Custom extensions for classes, structures, and functions. Atmos leverages user-defined types to implement its custom functions and extend YAML's capabilities.

Use-cases​

  • The !template YAML function is designed to evaluate and inject outputs containing maps or lists into the YAML document, whether generated by the atmos.Component template function or any Go template.

  • The !exec YAML function is used to execute shell scripts and assign the results to the sections in Atmos stack manifests

  • The !terraform.output YAML function allows you to access component outputs (remote state) directly within Atmos stack manifests. Note that this requires initializing each component (terraform init), which downloads all Terraform providers and may significantly impact performance.

  • The !store YAML function allows reading the values from a remote store (e.g. SSM Parameter Store, Artifactory, etc.) into Atmos stack manifests

  • The !env YAML function is used to retrieve environment variables and assign them to the sections in Atmos stack manifests

  • The !include YAML function allows downloading local or remote files from different sources, and assigning the file contents or individual values to the sections in Atmos stack manifests

tip

You can combine Atmos Stack Manifest Templating with Atmos YAML functions within the same stack configuration. Atmos processes templates first, followed by YAML functions, enabling you to dynamically provide parameters to the YAML functions.

Atmos sections supporting YAML functions​

You can use the YAML functions in all Atmos stack manifest sections:

  • vars
  • settings
  • env
  • metadata
  • command
  • component
  • providers
  • overrides
  • backend
  • backend_type
  • remote_state_backend
  • remote_state_backend_type

Examples​

stack.yaml

components:
  terraform:
    component2:
      settings:
        s1: !exec echo 's1'
      env:
        ENV_VAR_1: !template '{{ (atmos.Component "component3" .stack).settings.env.ENV_VAR_1 }}'
      vars:
        # Handle the output of type list from the `atmos.Component` template function
        test_1: !template '{{ toJson (atmos.Component "component1" "plat-ue2-dev").outputs.test_list }}'

        # Handle the output of type map from the `atmos.Component` template function
        test_2: !template '{{ toJson (atmos.Component "component1" .stack).outputs.test_map }}'

        # Execute the shell script and assign the result to the `test_3` variable
        test_3: !exec echo 42

        # Execute the shell script to get the `test_label_id` output from the `component1` component in the stack `plat-ue2-dev`
        test_4: !exec atmos terraform output component1 -s plat-ue2-dev --skip-init -- -json test_label_id

        # Execute the shell script to get the `test_map` output from the `component1` component in the current stack
        test_5: !exec atmos terraform output component1 -s {{ .stack }} --skip-init -- -json test_map

        # Execute the shell script to get the `test_list` output from the `component1` component in the current stack
        test_6: !exec atmos terraform output component1 -s {{ .stack }} --skip-init -- -json test_list

        # Get the `test_label_id` output of type string from the `component1` component in the stack `plat-ue2-dev`
        test_7: !terraform.output component1 plat-ue2-dev test_label_id

        # Get the `test_label_id` output of type string from the `component1` component in the current stack
        test_8: !terraform.output component1 {{ .stack }} test_label_id

        # Get the `test_list` output of type list from the `component1` component in the current stack
        test_9: !terraform.output component1 {{ .stack }} test_list

        # Get the `test_map` output of type map from the `component1` component in the current stack
        test_10: !terraform.output component1 {{ .stack }} test_map

        # Retrieve the value of an environment variable
        api_key: !env API_KEY

        # Include a local file
        config: !include ./dev-config.yaml

        # Download a remote file, query data from the file using a YQ expression, and assign the result to the variable
        allowed_ips: !include https://api.github.com/meta .api

Native Atmos YAML Functions​

Atmos natively supports the following YAML functions: