Skip to main content

!aws.account_id

The !aws.account_id YAML function retrieves the AWS account ID of the current caller identity by calling the AWS STS GetCallerIdentity API.

Usage​

The !aws.account_id function takes no parameters:

  # Get the AWS account ID of the current caller identity
  account_id: !aws.account_id

Arguments​

This function takes no arguments. It uses the AWS credentials from the environment or the Atmos authentication context if configured.

How It Works​

When processing the !aws.account_id YAML function, Atmos:

  1. Loads AWS Configuration - Uses the standard AWS SDK credential resolution chain:

    • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
    • Shared credentials file (~/.aws/credentials)
    • Shared config file (~/.aws/config)
    • EC2 Instance Metadata Service (IMDS)
    • ECS Task credentials
    • Web Identity Token credentials

  2. Calls STS GetCallerIdentity - Makes an API call to retrieve the caller identity

  3. Returns Account ID - Extracts and returns the 12-digit AWS account ID as a string

Atmos Auth Integration

When using Atmos Authentication, the function automatically uses credentials from the active identity. This enables seamless integration with SSO, assume role chains, and other authentication methods configured in your atmos.yaml.

Caching​

The !aws.account_id function caches its results in memory for the duration of the CLI invocation. This means:

  • Multiple uses of !aws.account_id in the same command only make one STS API call
  • Different authentication contexts (e.g., different profiles) get separate cache entries
  • Each new CLI command starts with a fresh cache

This caching significantly improves performance when the function is used in multiple places across your stack manifests.

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

Examples​

Basic Usage​

stack.yaml

components:
  terraform:
    my-component:
      vars:
        # Inject the AWS account ID into Terraform variables
        aws_account_id: !aws.account_id

Use in Backend Configuration​

stack.yaml

terraform:
  backend:
    s3:
      # Pass account ID to Terraform for constructing bucket names
      account_id: !aws.account_id

Conditional Logic with Account ID​

stack.yaml

components:
  terraform:
    security-baseline:
      vars:
        # Pass account ID for resource naming
        account_id: !aws.account_id

        # Use in tags
        tags:
          AccountId: !aws.account_id
          ManagedBy: "atmos"

Multiple Components Using Account ID​

stack.yaml

components:
  terraform:
    # Account ID is fetched once and cached
    vpc:
      vars:
        account_id: !aws.account_id

    eks:
      vars:
        account_id: !aws.account_id  # Uses cached value

    rds:
      vars:
        account_id: !aws.account_id  # Uses cached value

Comparison with Terragrunt​

This function is equivalent to Terragrunt's get_aws_account_id() function:

TerragruntAtmos
get_aws_account_id()!aws.account_id

Error Handling​

If the function fails to retrieve the AWS caller identity (e.g., no credentials available, network issues, or insufficient permissions), Atmos will log an error and exit.

Common error scenarios:

  • No AWS credentials configured
  • Expired credentials
  • Network connectivity issues
  • Missing STS permissions

Considerations​

  • Requires valid AWS credentials - The function will fail if no valid credentials are available
  • Network dependency - Requires connectivity to AWS STS endpoint
  • Performance - Results are cached per CLI invocation, so there's minimal overhead when used multiple times
  • IAM permissions - Requires sts:GetCallerIdentity permission (usually available to all authenticated principals)