How to Use Provider Alias in Terraform for Multiple Provider Configurations

In Terraform, use alias inside a provider block to create multiple named configurations of the same provider. Reference these aliases in resource blocks with provider = aws. to use the specific provider instance.

Syntax

The alias argument inside a provider block defines a named instance of that provider. You then use this alias in resource blocks to specify which provider configuration to use.

• provider "" { alias = "" ... }: Defines a provider instance with an alias.
• resource "" "" { provider = aws. ... }: Uses the aliased provider for this resource.

terraform

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

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

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

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

Example

This example shows how to create two AWS S3 buckets in different regions by using provider aliases. The default provider creates a bucket in us-east-1, and the aliased provider west creates a bucket in us-west-2.

terraform

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 = "my-east-bucket-terraform-example"
  acl    = "private"
}

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

Output

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

Common Pitfalls

Common mistakes when using provider aliases include:

• Not specifying the provider attribute in resources that should use the aliased provider, causing them to use the default provider instead.
• Using the same alias name in multiple provider blocks, which causes conflicts.
• Forgetting to configure the aliased provider block properly, such as missing required arguments like region.

Always ensure each alias is unique and referenced correctly.

terraform

/* Wrong: Missing provider attribute, resource uses default provider */
resource "aws_s3_bucket" "west_bucket" {
  bucket = "my-west-bucket"
  acl    = "private"
}

/* Right: Specify provider alias to use the correct provider */
resource "aws_s3_bucket" "west_bucket" {
  provider = aws.west
  bucket   = "my-west-bucket"
  acl      = "private"
}

Quick Reference

Tips for using provider aliases in Terraform:

• Use alias to define multiple provider configurations.
• Reference aliased providers in resources with provider = aws..
• Keep alias names unique and descriptive.
• Configure all required provider arguments for each alias.
• Use aliases to manage resources across multiple regions or accounts.

Key Takeaways

Use the alias argument inside provider blocks to create multiple provider configurations.

Reference the aliased provider in resource blocks with provider = aws..

Each alias must be unique and fully configured with required settings like region.

Without specifying provider, resources use the default provider configuration.

Provider aliases help manage resources across different regions or accounts easily.