Skip to main content

Atmos YAML Functions

Recommended

YAML Functions are the recommended way to add dynamic behavior to your Atmos configurations. They are native YAML features that work with the YAML parser, making them type-safe, predictable, and error-resistant. Unlike template functions which manipulate raw text, YAML functions operate on structured data after parsing.

Explicit tags and quoted strings​

Keep the function tag outside the quotes: foo: !env "SOMETHING" reads the environment variable, while foo: "!env SOMETHING" is literal text. This applies to all YAML functions from edition 2026-10-20, including unpinned projects. Earlier editions retain legacy string-prefix evaluation. See the migration guide.

Using a function value in a template​

Templates render before YAML functions run, and Atmos carries the function through rendering so it can fill in the value afterward. This works when a template places the value in a string:

vars:
  region: !env AWS_REGION
  stage: dev
components:
  terraform:
    app:
      vars:
        name: "app-{{ .vars.region }}-{{ .vars.stage }}"  # app-us-east-1-dev

The function must return a single value such as a string or number. A map or list inside a larger string fails with an error.

Template functions and conditions on vars run before the value exists. {{ .vars.region | upper }} fails with an error, and {{ if eq .vars.region "us-east-1" }} compares against the unevaluated function rather than the region. Declare the function in locals when a template needs to act on the result, as in {{ .locals.region | upper }}.

Why YAML Functions Are Safer​

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.

Key advantages over template functions:

  • Cannot break YAML syntax - Functions execute after YAML parsing, not before
  • Type-safe - Work with actual YAML types, not raw strings
  • No indentation issues - The YAML structure is already established
  • Clear error messages - Errors point to specific YAML nodes, not parsing failures
  • Predictable behavior - Always return valid YAML data structures

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 !starlark YAML function computes typed configuration values using functions, conditions, and the merged component context.

  • The !append YAML function concatenates lists during stack inheritance instead of replacing them, providing fine-grained control over list merging behavior on a per-field basis

  • 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/tofu init), which initializes all Terraform/OpenTofu modules and downloads all Terraform/OpenTofu providers, which may significantly impact performance. Consider using !store or !terraform.state functions instead, which don't have this performance penalty.

  • The !terraform.state YAML function reads outputs directly from the configured Terraform or OpenTofu backend, without initializing providers or running Terraform — it's very fast and currently supports S3 and local backends for accessing remote state.

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

  • The !store.get YAML function allows retrieving arbitrary keys directly from a store without following the Atmos stack/component/key naming convention. This is useful for accessing values stored by external systems or for retrieving global configuration that doesn't belong to a specific component.

  • 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.

  • 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 !env YAML function is used to retrieve environment variables and assign them to the sections in Atmos stack manifests.

  • The !repo-root YAML function is used to retrieve the root directory of the Atmos repository.

  • The !git.repository, !git.owner, !git.name, !git.host, and !git.url YAML functions retrieve repository metadata (the <owner>/<name> slug, owner, name, host, and remote URL) from the current Git repository.

  • The !git.sha, !git.ref, and !git.branch YAML functions retrieve the current commit SHA (!git.sha and its source-pinning alias !git.ref) and the current branch name.

  • The !git.root YAML function is an alias of !repo-root that retrieves the root directory of the current Git repository.

  • The !emulator YAML function retrieves connection information (endpoint, credentials, kubeconfig) from a running emulator component.

  • The !cwd YAML function is used to retrieve the current working directory where Atmos is executed from. Useful when you need paths relative to where you run Atmos rather than relative to the configuration file.

  • The !unset YAML function is used to delete or remove keys from the configuration during inheritance and merging. This allows you to explicitly remove values that were defined in parent configurations or imports, providing fine-grained control over configuration inheritance

  • The !random YAML function generates a cryptographically secure random integer within a specified range, useful for generating random port numbers or IDs.

  • The !literal YAML function preserves values exactly as written, bypassing all template processing. Use it to pass template-like syntax (e.g., {{...}} or ${...}) to downstream tools like Terraform, Helm, or ArgoCD without Atmos attempting to evaluate them. It also works in atmos.yaml and on the script and command of custom command, workflow, and hook steps.

  • The !version YAML function resolves a value from the active Atmos-managed version track lock file. Use it for locked toolchain versions, image tags, GitHub Actions refs, and other external version values.

  • The !aws.account_id YAML function retrieves the AWS account ID of the current caller identity using STS GetCallerIdentity.

  • The !aws.caller_identity_arn YAML function retrieves the full ARN of the current AWS caller identity using STS GetCallerIdentity.

  • The !aws.caller_identity_user_id YAML function retrieves the unique user ID of the current AWS caller identity using STS GetCallerIdentity.

  • The !aws.region YAML function retrieves the AWS region from the current SDK configuration.

  • The !aws.cloudformation.output YAML function allows you to read the deployed Outputs of a native aws/cloudformation component directly within Atmos stack manifests — the Terraform↔CloudFormation interop bridge, sibling to !terraform.output.

  • The !tags and !labels YAML functions return the current component's own metadata.tags (list) and metadata.labels (map), typed correctly with no !template/toJson boilerplate — commonly used to bridge metadata.labels into the vars.tags/vars.labels a terraform-null-label-style module expects. !labels.keys and !labels.values return just the keys or values of metadata.labels as a flat list. Use !labels key [default] to read one label, with an optional fallback when the key is absent.

  • The !ci.labels YAML function reads the live labels on the current CI pull request (or, for merge queue runs, the queued pull request) and returns either the sorted label list or a boolean for !ci.labels [preview]. Use it to drive settings.pro.enabled, metadata.enabled, or metadata.labels from the review, then select with --labels preview:true.

tip

You can combine Atmos Stack Manifest Templating with Atmos YAML functions within the same stack configuration. Post-merge stack value functions can consume component template results. Load-time includes, merge directives, and field-specific functions run at different stages; see YAML function scope and evaluation.

Atmos sections supporting YAML functions​

YAML functions work in values that reach the stack/component evaluator, including vars, settings, env, providers, and backend values. Support is specific to the function and consumer: import paths and structural fields may be needed before component evaluation, and workflow fields do not automatically use the stack evaluator.

CLI configuration, stack manifests, workflows, custom commands, hooks, vendor manifests, and scaffolds have different function sets. Consult the scope matrix and each function's availability section before moving an example between them. Run atmos doctor --only yaml-functions to diagnose unsupported uses without executing the functions.

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.state component1 {{ .stack }} test_list

        # Get the `test_map` output of type map from the `component1` component in the current stack
        test_10: !terraform.state 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 JSON file with .json extension and query data using YQ
        # Note: URLs without extensions are treated as text, so use URLs with appropriate extensions
        github_data: !include ./github-meta.json .api

        # Remove a key that was defined in a parent configuration or import
        deprecated_setting: !unset

        # Remove specific nested configuration
        legacy:
          old_feature: !unset

        # Generate a random port number between 1024 and 65535
        app_port: !random 1024 65535

        # Get the current AWS account ID
        aws_account_id: !aws.account_id

        # Get the ARN of the current AWS caller identity
        aws_caller_arn: !aws.caller_identity_arn

        # Get the unique user ID of the current AWS caller identity
        aws_user_id: !aws.caller_identity_user_id

        # Get the current AWS region
        aws_region: !aws.region

        # Read the `VpcId` Output of a native aws/cloudformation component in the current stack
        vpc_id: !aws.cloudformation.output vpc VpcId

        # Preserve template syntax for downstream tools (Terraform, Helm, ArgoCD)
        helm_annotation: !literal "{{ .Values.ingress.class }}"
        terraform_var: !literal "${var.hostname}"
        db_users: [!literal "{{external.email}}", !literal "{{external.admin}}"]

        # Get this component's own metadata.tags (list) and metadata.labels (map)
        component_tags: !tags
        component_labels: !labels

        # Bridge metadata.labels into the var.tags a terraform-null-label-style module expects
        tags: !labels

      metadata:
        tags: [production, networking]
        labels:
          cost-center: platform
          compliance: sox

      dependencies:
        # Append to an inherited list instead of replacing it
        components: !append
          - name: additional-component-1
          - name: additional-component-2

Native Atmos YAML Functions​

Atmos natively supports the following YAML functions: