Providers allow Terraform to interact with cloud providers, SaaS providers, andother APIs.
Some providers require you to configure them with endpoint URLs, cloud regions,or other settings before Terraform can use them. This page documents how toconfigure settings for providers.
Additionally, all Terraform configurations must declare which providers theyrequire so that Terraform can install and use them. TheProvider Requirementspage documents how to declare providers so Terraform can install them.
Provider configurations belong in the root module of a Terraform configuration.(Child modules receive their provider configurations from the root module; formore information, seeThe Module providers Meta-Argumentand Module Development: Providers Within Modules.)
A provider configuration is created using a provider block:
provider "google" { project = "acme-app" region = "us-central1"}The name given in the block header ("google" in this example) is thelocal name of the provider toconfigure. This provider should already be included in a required_providersblock.
The body of the block (between { and }) contains configuration arguments forthe provider. Most arguments in this section are defined by the provider itself;in this example both project and region are specific to the googleprovider.
You can use expressions in the values of theseconfiguration arguments, but can only reference values that are known before theconfiguration is applied. This means you can safely reference input variables,but not attributes exported by resources (with an exception for resourcearguments that are specified directly in the configuration).
A provider's documentation should list which configuration arguments it expects.For providers distributed on theTerraform Registry, versioned documentation isavailable on each provider's page, via the "Documentation" link in theprovider's header.
Some providers can use shell environment variables (or other alternate sources,like VM instance profiles) as values for some of their arguments; whenavailable, we recommend using this as a way to keep credentials out of yourversion-controlled Terraform code.
There are also two "meta-arguments" that are defined by Terraform itselfand available for all provider blocks:
- alias, for using the same provider with different configurations for different resources
- version, which we no longer recommend (useprovider requirements instead)
Unlike many other objects in the Terraform language, a provider block maybe omitted if its contents would otherwise be empty. Terraform assumes anempty default configuration for any provider that is not explicitly configured.
alias: Multiple Provider Configurations
You can optionally define multiple configurations for the same provider, andselect which one to use on a per-resource or per-module basis. The primaryreason for this is to support multiple regions for a cloud platform; otherexamples include targeting multiple Docker hosts, multiple Consul hosts, etc.
To create multiple configurations for a given provider, include multipleprovider blocks with the same provider name. For each additional non-defaultconfiguration, 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 analternate provider configuration from the parent module, add theconfiguration_aliases argument to that provider's required_providersentry. The following example declares both the mycloud andmycloud.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 configurationfor that provider. Resources that don't set the provider meta-argument willuse the default provider configuration that matches the first word of theresource type name. (For example, an aws_instance resource uses the defaultaws provider configuration unless otherwise stated.)
If every explicit configuration of a provider has an alias, Terraform uses theimplied empty configuration as that provider's default configuration. (If theprovider has any required configuration arguments, Terraform will raise an errorwhen resources default to the empty configuration.)
Referring to Alternate Provider Configurations
When Terraform needs the name of a provider configuration, it expects areference 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 namedentities (for example, var.image_id), they aren't strings and don't need to bequoted. 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 analias argument) inferred from the first word of the resource type name.
To use an alternate provider configuration for a resource or data source, setit* 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 itsproviders meta-argument to specify which provider configurations should bemapped 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; seeThe Module providers Meta-Argumentfor more details. In most cases, only root modules should define providerconfigurations, with all child modules obtaining their provider configurationsfrom their parents.
The version meta-argument specifies a version constraint for a provider, andworks the same way as the version argument in arequired_providers block. The versionconstraint in a provider configuration is only used if required_providersdoes not include one for that provider.
~Warning: The version argument in provider configurations is deprecated, and we will remove it in a future Terraform version.
In Terraform 0.13 and later, always declare provider version constraints inthe required_providers block.
