How Terraform uses provider aliases for multiple configurations and state to map configuration addresses to remote objects.
One Terraform configuration can use several providers, such as AWS and GitHub, and it can also use several configurations of the same provider. A provider alias names a non-default configuration, commonly for a second region, account, or credential context. Terraform state solves a different problem: it records the bindings between resource addresses in configuration and the real objects Terraform manages. HashiCorp’s provider documentation and state-purpose reference describe these separate mechanisms.
| Need | Terraform mechanism |
|---|---|
| Manage a GitHub repository and an AWS bucket in one root module. | Declare the github and aws providers. |
| Manage AWS resources in two regions in the same run. | Define a default AWS configuration and an aliased AWS configuration. |
| Point a resource at the non-default AWS configuration. | Set the resource’s provider meta-argument. |
| Let a child module use a non-default configuration. | Pass it explicitly with the module providers map. |
This example creates the default AWS configuration for Central Canada and an aliased configuration for US East. The aws_s3_bucket.disaster_recovery resource explicitly uses the alias.
1provider "aws" {
2 region = "ca-central-1"
3}
4
5provider "aws" {
6 alias = "us_east"
7 region = "us-east-1"
8}
9
10resource "aws_s3_bucket" "primary" {
11 bucket = "example-primary-bucket"
12}
13
14resource "aws_s3_bucket" "disaster_recovery" {
15 provider = aws.us_east
16 bucket = "example-dr-bucket"
17}
The unaliased provider block is the default. If every provider block is aliased, Terraform creates an implied empty default configuration; a resource that forgets its provider argument can then fail or use unexpected defaults. Keep the default explicit unless a configuration has a compelling reason not to.
Terraform needs state to identify which remote object belongs to each resource instance. State also records metadata, including the provider configuration most recently used by a resource when aliases are involved. State is not a general inventory of every object in an account: it represents the objects that Terraform is configured to manage.
Each remote object should be bound to only one Terraform resource instance. Binding the same object twice makes future plans ambiguous and can cause unexpected behavior. This matters when importing pre-existing infrastructure: import it to the one intended address, then bring configuration and state into agreement.
These terms are easy to conflate, but they address different boundaries:
| Term | Separates or selects |
|---|---|
| Provider alias | A provider configuration used by resources or modules in one configuration. |
| Workspace | A distinct state instance for the same configuration, depending on the backend. |
| Backend | Where state is stored and, for capable backends, how state locking is coordinated. |
A workspace is not a second AWS region, and an alias is not a separate state file. A deployment may use both: aliases for two regions and separate state for development and production. Choose the separation based on ownership, lifecycle, access controls, and the risk of applying changes to the wrong environment.
Because state can contain sensitive data and determines what Terraform will manage, protect it with access controls and do not commit it to version control. For team use, a remote backend with locking avoids competing applies from independently copied local state.