alias: Multiple Provider Configurations
You can optionally define multiple configurations for the same provider, and select which one to use on a per-resource or per-module basis. The primary reason for this is to support multiple regions for a cloud platform; other examples include targeting multiple Docker hosts, multiple Consul hosts, etc.
To create multiple configurations for a given provider, include multiple provider blocks with the same provider name. For each additional non-default configuration, use the alias meta-argument to provide an extra name segment. For example:
# The default provider configuration; resources that begin with `aws_` will use
# it as the default, and it can be referenced as `aws`.
provider "aws" {
region = "us-east-1"
}
# Additional provider configuration for west coast region; resources can
# reference this as `aws.west`.
provider "aws" {
alias = "west"
region = "us-west-2"
}
To declare a configuration alias within a module in order to receive an alternate provider configuration from the parent module, add the configuration_aliases argument to that provider’s required_providers entry. The following example declares both the mycloud and mycloud.alternate provider configuration names within the containing module:
terraform {
required_providers {
mycloud = {
source = "mycorp/mycloud"
version = "~> 1.0"
configuration_aliases = [ mycloud.alternate ]
}
}
}
Default Provider Configurations
A provider block without an alias argument is the default configuration for that provider. Resources that don’t set the provider meta-argument will use the default provider configuration that matches the first word of the resource type name. (For example, an aws_instance resource uses the default aws provider configuration unless otherwise stated.)
If every explicit configuration of a provider has an alias, Terraform uses the implied empty configuration as that provider’s default configuration. (If the provider has any required configuration arguments, Terraform will raise an error when resources default to the empty configuration.)
Referring to Alternate Provider Configurations
When Terraform needs the name of a provider configuration, it expects a reference of the form <PROVIDER NAME>.<ALIAS>. In the example above, aws.west would refer to the provider with the us-west-2 region.
These references are special expressions. Like references to other named entities (for example, var.image_id), they aren’t strings and don’t need to be quoted. But they are only valid in specific meta-arguments of resource, data, and module blocks, and can’t be used in arbitrary expressions.
Selecting Alternate Provider Configurations
By default, resources use a default provider configuration (one without an alias argument) inferred from the first word of the resource type name.
To use an alternate provider configuration for a resource or data source, set its provider meta-argument to a <PROVIDER NAME>.<ALIAS> reference:
resource "aws_instance" "foo" {
provider = aws.west
# ...
}
To select alternate provider configurations for a child module, use its providers meta-argument to specify which provider configurations should be mapped to which local provider names inside the module:
module "aws_vpc" {
source = "./aws_vpc"
providers = {
aws = aws.west
}
}
Modules have some special requirements when passing in providers; see The Module providers Meta-Argument for more details. In most cases, only root modules should define provider configurations, with all child modules obtaining their provider configurations from their parents.