Skip to main content

!aws.cloudformation.output

The !aws.cloudformation.output YAML function reads the deployed Outputs of a native aws/cloudformation component directly in Atmos stack manifests, by calling the CloudFormation DescribeStacks API. It is the Terraform↔CloudFormation interop bridge: the sibling of !terraform.output, but for aws/cloudformation targets instead of Terraform/OpenTofu ones.

Experimental

Usage​

The !aws.cloudformation.output function is called with either two or three parameters:

  # Get the `output-key` Output of the `component` in the current stack
  !aws.cloudformation.output <component> <output-key>

  # Get the `output-key` Output of the `component` in the provided `stack`
  !aws.cloudformation.output <component> <stack> <output-key>

Arguments​

component
The aws/cloudformation component name.
stack
(Optional) Atmos stack name. Defaults to the current stack when omitted.
output-key

The exact CloudFormation Output's logical key (the value of the Outputs.<key> entry in the target's template). Unlike !terraform.output, this is a direct lookup by key, not a YQ expression — CloudFormation Outputs are always a flat key/value map, so there is nothing to query into.

tip

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

Type-Aware Merging

Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts. See the full explanation: YAML Function Merging

Requirements​

  • The target component must be a native aws/cloudformation component with a resolved stack_name — !aws.cloudformation.output errors if the target has no stack_name configured.
  • The target stack must already be deployed. !aws.cloudformation.output calls the live DescribeStacks API; there is no local-state equivalent (aws/cloudformation has no Terraform/OpenTofu-style state file to read instead).
  • The target stack must hold deployed resources. A stack that only holds a preview changeset (REVIEW_IN_PROGRESS, left behind by diff or plan on a component that was never applied) or that failed to create (ROLLBACK_COMPLETE, ROLLBACK_FAILED, CREATE_FAILED), or is being deleted (DELETE_*), is an error: stack "<name>" has status <status>. Apply the target component first.
  • The output-key must exist. A key the stack does not declare is an error that lists the keys it does have, instead of resolving to null. A key that exists with an empty value is not an error.
  • Resolving the function requires AWS authentication — it uses the target component's own auth if it authenticates independently, otherwise the enclosing component's (propagated from --identity).

Examples​

stack.yaml
components:
  terraform:
    my_lambda_component:
      vars:
        # Read the `VpcId` Output of the aws/cloudformation `vpc` component in the current stack
        vpc_id: !aws.cloudformation.output vpc VpcId

        # Read an Output from a different, hardcoded stack
        shared_bucket: !aws.cloudformation.output logging plat-ue2-audit LogBucketName

        # Use the `.stack` template identifier to reference the current stack explicitly
        subnet_ids: !aws.cloudformation.output vpc {{ .stack }} PrivateSubnetIds

Output lookups​

Atmos does not cache the result of the !aws.cloudformation.output function. Every evaluation of the function calls DescribeStacks again, so each use in your manifests costs one API call, and the value always reflects the deployed stack at that moment.

The atmos.Component template function resolves .outputs through the same lookup and caches the component's sections for the duration of one Atmos command. Use it when several values come from the same component and you want a single API call.

Considerations​

  • !aws.cloudformation.output is not allowed in metadata.tags or metadata.labels values — the same restriction as !terraform.output. Selectors (--tags/--labels) drive component-scoping decisions before evaluation, so they must be resolvable without authentication, API calls, or nondeterminism.

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

  • Consider cold-start scenarios: if the dependent aws/cloudformation stack does not exist, or exists without deployed resources (for example REVIEW_IN_PROGRESS after a diff), the function returns an error. A misspelled output-key is an error too, so a typo cannot reach the consuming component as an empty value.

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

See Also​