Region Configuration

The region configuration capability provides functionality for resolving AWS region from the EC2 Instance Metadata Service (IMDS).

Overview

The UseEC2IMDSRegion type enables automatic region detection from EC2 Instance Metadata Service when running on EC2 instances. This is useful for applications that need to automatically determine their region based on the EC2 instance location.

API

type UseEC2IMDSRegion struct {
    Client *imds.Client
}

Fields:

• Client - Optional EC2 Instance Metadata Service client. If unset, defaults to a generic EC2 IMDS client.

Usage

Enable EC2 IMDS Region Resolution

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/aws/aws-sdk-go-v2/config"
)

func main() {
    // Enable EC2 IMDS region resolution
    cfg, err := config.LoadDefaultConfig(
        context.TODO(),
        config.WithEC2IMDSRegion(),
    )
    if err != nil {
        log.Fatalf("unable to load SDK config, %v", err)
    }

    fmt.Printf("Detected region from EC2 IMDS: %s\n", cfg.Region)
}

Custom EC2 IMDS Client

import (
    "github.com/aws/aws-sdk-go-v2/feature/ec2/imds"
    "time"
)

// Create custom IMDS client with specific options
customIMDSClient := imds.New(imds.Options{
    Endpoint: "http://169.254.169.254",
})

cfg, err := config.LoadDefaultConfig(
    context.TODO(),
    config.WithEC2IMDSRegion(func(o *config.UseEC2IMDSRegion) {
        o.Client = customIMDSClient
    }),
)
if err != nil {
    log.Fatal(err)
}

Fallback Region with EC2 IMDS

// Try EC2 IMDS first, fall back to default region if not on EC2
cfg, err := config.LoadDefaultConfig(
    context.TODO(),
    config.WithEC2IMDSRegion(),
    config.WithDefaultRegion("us-east-1"),
)
if err != nil {
    log.Fatal(err)
}

Region Resolution Precedence

When loading configuration, regions are resolved in the following order (first match wins):

1. Explicit WithRegion option - Highest priority
2. Environment variable - AWS_REGION or AWS_DEFAULT_REGION
3. Shared configuration profile - Region from ~/.aws/config
4. EC2 IMDS - If WithEC2IMDSRegion is configured
5. Default region - If WithDefaultRegion is configured

EC2 Instance Metadata Service

The EC2 Instance Metadata Service (IMDS) is a service available to EC2 instances that provides information about the instance, including:

• Region
• Availability zone
• Instance type
• IAM role credentials
• And more

IMDS Endpoints

By default, IMDS is available at:

• IPv4: http://169.254.169.254
• IPv6: http://[fd00:ec2::254]

IMDS Versions

EC2 supports two versions of IMDS:

• IMDSv1 - Request/response method (less secure)
• IMDSv2 - Session-oriented method (more secure, requires token)

The SDK defaults to using IMDSv2 with automatic fallback to IMDSv1 unless disabled.

Related Configuration

Disable EC2 IMDS

import (
    "github.com/aws/aws-sdk-go-v2/feature/ec2/imds"
)

cfg, err := config.LoadDefaultConfig(
    context.TODO(),
    config.WithEC2IMDSClientEnableState(imds.ClientDisabled),
)

Configure IMDS Endpoint Mode

// Use IPv6 IMDS endpoint
cfg, err := config.LoadDefaultConfig(
    context.TODO(),
    config.WithEC2IMDSEndpointMode(imds.EndpointModeStateIPv6),
)

Custom IMDS Endpoint

cfg, err := config.LoadDefaultConfig(
    context.TODO(),
    config.WithEC2IMDSEndpoint("http://169.254.169.254"),
)

Disable IMDSv1 Fallback

Disable fallback to IMDSv1 for improved security:

import (
    "os"
)

// Via environment variable (recommended)
os.Setenv("AWS_EC2_METADATA_V1_DISABLED", "true")

cfg, err := config.LoadDefaultConfig(context.TODO())

Error Handling

When EC2 IMDS region resolution fails (e.g., not running on EC2), the SDK continues with other region sources:

// This will not fail if IMDS is unavailable
// It will fall back to environment variables or default region
cfg, err := config.LoadDefaultConfig(
    context.TODO(),
    config.WithEC2IMDSRegion(),
    config.WithDefaultRegion("us-east-1"), // Fallback
)
if err != nil {
    log.Fatal(err)
}

// The region will be from IMDS if available, otherwise from default
fmt.Printf("Region: %s\n", cfg.Region)

Best Practices

1. Use with Fallback: Always provide a default region as fallback when using EC2 IMDS region resolution
2. IMDSv2 Only: In production, consider disabling IMDSv1 fallback for better security
3. Custom Endpoints: Only use custom IMDS endpoints in specialized environments (e.g., testing)
4. Context Timeouts: Use contexts with appropriate timeouts to prevent hanging on IMDS requests