Skip to main content

!aws.region

The !aws.region YAML function retrieves the AWS region from the current SDK configuration. This is the region that would be used for AWS API calls.

Usage​

The !aws.region function takes no parameters:

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

Arguments​

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

How It Works​

When processing the !aws.region 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 Region - Extracts and returns the region from the loaded AWS configuration

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.region function shares its cache with other AWS identity functions (!aws.account_id, !aws.caller_identity_arn, !aws.caller_identity_user_id). This means:

  • All AWS identity functions share a single STS API call
  • Results are cached per CLI invocation
  • Different authentication contexts get separate cache entries
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 region into Terraform variables
        aws_region: !aws.region

Provider Configuration​

stack.yaml
components:
  terraform:
    vpc:
      vars:
        # Use the current region for the VPC
        region: !aws.region

      providers:
        aws:
          region: !aws.region

Resource Naming with Region​

stack.yaml
components:
  terraform:
    s3-bucket:
      vars:
        # Pass region as separate var for Terraform to construct names
        aws_region: !aws.region

        tags:
          Region: !aws.region
          Environment: "production"

Combined with Other AWS Functions​

stack.yaml
components:
  terraform:
    infrastructure:
      vars:
        # All AWS functions share the same cached STS call
        aws_account_id: !aws.account_id
        aws_region: !aws.region
        caller_arn: !aws.caller_identity_arn

Cross-Region Configuration​

stack.yaml
components:
  terraform:
    replication-config:
      vars:
        # Use the current region as the source
        source_region: !aws.region

        # Replicate to a different region (hardcoded destination)
        destination_region: "eu-west-1"

Region Resolution Order​

The region is resolved in the following order:

  1. Atmos Auth Context - If using Atmos authentication with a region specified
  2. AWS_REGION environment variable
  3. AWS_DEFAULT_REGION environment variable
  4. Shared config file (~/.aws/config) - The region setting for the active profile
  5. Instance metadata - For EC2 instances or ECS tasks

Error Handling​

If the function fails to determine the AWS region (e.g., no credentials available, no region configured), Atmos will log an error and exit.

Common error scenarios:

  • No AWS credentials configured
  • No region specified in credentials, config, or environment
  • Network connectivity issues (for STS call)

Considerations​

  • Requires valid AWS credentials - The function needs credentials to make the STS call
  • Region must be configured - Either via environment, config file, or Atmos auth
  • Performance - Results are cached and shared with other AWS identity functions
  • IAM permissions - Requires sts:GetCallerIdentity permission

Related Functions​