Provider aliases for multi-region in Terraform - Commands & Configuration

Introduction

When you want to manage resources in multiple cloud regions using Terraform, you need a way to tell Terraform which region to use for each resource. Provider aliases let you configure multiple versions of the same provider, each set to a different region, so you can deploy resources across regions in one Terraform project.

When you want to deploy a virtual machine in us-east-1 and another in us-west-2 within the same Terraform configuration.

When you manage a database in one region and a storage bucket in another region for latency or compliance reasons.

When you need to test your infrastructure in multiple regions without duplicating your Terraform code.

When you want to keep your infrastructure organized but still use one Terraform state file for multiple regions.

When you want to automate disaster recovery by deploying resources in a secondary region.

Config File - main.tf

main.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

resource "aws_s3_bucket" "east_bucket" {
  bucket = "example-bucket-east-12345"
  acl    = "private"
}

resource "aws_s3_bucket" "west_bucket" {
  provider = aws.west
  bucket   = "example-bucket-west-12345"
  acl      = "private"
}

The terraform block sets the AWS provider version.

The first provider "aws" block configures the default AWS provider for the us-east-1 region.

The second provider "aws" block uses the alias "west" to configure AWS for the us-west-2 region.

The aws_s3_bucket.east_bucket resource uses the default provider and creates a bucket in us-east-1.

The aws_s3_bucket.west_bucket resource specifies provider = aws.west to use the aliased provider and creates a bucket in us-west-2.

Commands

This command initializes the Terraform working directory, downloads the AWS provider plugin, and prepares Terraform to manage resources.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding hashicorp/aws versions matching "~> 4.0"...

- Installing hashicorp/aws v4.60.0...

- Installed hashicorp/aws v4.60.0 (signed by HashiCorp)



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see

any changes that are required for your infrastructure. All Terraform commands

should now work.

This command shows what Terraform will create or change. It verifies that the configuration is valid and previews the resources to be created in both regions.

Terminal

terraform plan

Expected Output

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:

  + create



Terraform will perform the following actions:



  # aws_s3_bucket.east_bucket will be created

  + resource "aws_s3_bucket" "east_bucket" {

      + acl    = "private"

      + bucket = "example-bucket-east-12345"

      + id     = (known after apply)

    }



  # aws_s3_bucket.west_bucket will be created

  + resource "aws_s3_bucket" "west_bucket" {

      + acl    = "private"

      + bucket = "example-bucket-west-12345"

      + id     = (known after apply)

    }



Plan: 2 to add, 0 to change, 0 to destroy.

This command applies the planned changes and creates the S3 buckets in both regions without asking for confirmation.

Terminal

terraform apply -auto-approve

Expected Output

aws_s3_bucket.east_bucket: Creating...

aws_s3_bucket.west_bucket: Creating...

aws_s3_bucket.east_bucket: Creation complete after 2s [id=example-bucket-east-12345]

aws_s3_bucket.west_bucket: Creation complete after 2s [id=example-bucket-west-12345]



Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

→

-auto-approve - Skips interactive approval before applying changes

This command lists all resources Terraform manages in the current state, showing both buckets in different regions.

Terminal

terraform state list

Expected Output

aws_s3_bucket.east_bucket

aws_s3_bucket.west_bucket

Key Concept

If you remember nothing else from this pattern, remember: provider aliases let you configure multiple regions by naming each provider separately and assigning resources to the right one.

Common Mistakes

Not specifying the provider alias in the resource block for the second region.

Terraform will use the default provider for all resources, causing resources to be created in the wrong region.

Always add the provider attribute with the correct alias, like provider = aws.west, to resources meant for the non-default region.

Using the same bucket name in both regions.

S3 bucket names must be globally unique, so Terraform will fail to create the second bucket if the name is reused.

Use unique bucket names for each region to avoid conflicts.

Summary

Define multiple provider blocks with different regions using aliases.

Assign resources to the correct provider using the provider attribute with the alias.

Use terraform init, plan, and apply to deploy resources across regions in one configuration.