# !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:

```yaml
  # 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

:::note Atmos Auth Integration
When using [Atmos Authentication](/cli/commands/auth/usage), 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

:::note 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](/reference/yaml-function-merging)
:::

## Examples

### Basic Usage

**File:** `stack.yaml`

```yaml
components:
  terraform:
    my-component:
      vars:
        # Inject the AWS region into Terraform variables
        aws_region: !aws.region
```

### Provider Configuration

**File:** `stack.yaml`

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

      providers:
        aws:
          region: !aws.region
```

### Resource Naming with Region

**File:** `stack.yaml`

```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

**File:** `stack.yaml`

```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

**File:** `stack.yaml`

```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

- [!aws.account\_id](/functions/yaml/aws.account-id) - Get the AWS account ID
- [!aws.caller\_identity\_arn](/functions/yaml/aws.caller-identity-arn) - Get the full ARN
- [!aws.caller\_identity\_user\_id](/functions/yaml/aws.caller-identity-user-id) - Get the user ID
- [!aws.organization\_id](/functions/yaml/aws.organization-id) - Get the AWS Organization ID