providers reference

By default, child modules inherit the default provider configurations of their parent module. You can specify an alternate provider configuration in the module block using the providers argument. The providers argument instructs Terraform to use the reference provider configuration to create the module resources.

Usage

In a module block, you can add the optional providers meta-argument to specify which provider configurations from the parent module is available inside the child module.

The value of providers is a map, where the keys are the provider configuration names used inside the child module and the values are provider configuration names from the parent module.

Keys and values are unquoted references to provider configurations. For default configurations, the reference is the local name of the provider. For alternate configurations, the reference uses a <PROVIDER>.<ALIAS> format.

Within a child module, either Terraform chooses a default based on the name of the resource type, or the resource specifies an alternate configuration with the provider argument. If the module receives a providers map when it's called, the provider configuration names used within the module are effectively remapped to refer the specified configurations from the parent module.

In the following example, Terraform uses the default aws configuration for AWS resources in the root module where no explicit provider instance is selected, but the example child moduleuses the alternate configuration with the alias usw2. As a result, any AWS resources the module defines uses the us-west-2 region.

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

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

module "example" {
  source    = "./example"
  providers = {
    aws = aws.usw2
  }
}

Default behavior

The providers argument is optional when the child module does not declare a configuration_aliases. When you omit the argument, a child module inherits all of the default provider configurations from its parent module. Default provider configurations are configurations that don't have an alias argument.

Specifying a providers argument cancels the default behavior. As a result, the child module only has access to the provider configurations you specify.

When to specify `providers`

Add the providers argument when one of the following conditions apply:

Using different default provider configurations for a child module.
Configuring a module that requires multiple configurations of the same provider.

Change default provider configurations

Most re-usable modules only use default provider configurations, which they can automatically inherit from their caller when providers is omitted.

However, in Terraform configurations that use multiple configurations of the same provider, you might want some child modules to use the default provider configuration and others to use an alternate. A common use case is using one configuration to manage resources in multiple different regions of the same cloud provider.

Using providers argument lets you accommodate this without needing to edit the child module. Although the code within the child module always refers to the default provider configuration, the actual configuration of that default can be different for each instance.

Information for module developers

For more details and guidance about working with providers inside a re-usable child module, refer to Providers Within Modules.

Supported constructs

You can use providers in the following Terraform configuration blocks:

module blocks

You can use providers in the following Stack configuration blocks:

Example use cases

The following use cases describe common patterns for the providers argument.

Modules with alternate provider configurations

In rare cases, a single re-usable module might require multiple configurations of the same provider. For example, a module that configures connectivity between networks in two AWS regions is likely to need both a source and a destination region.

In the following example, the tunnel module includes resources that support their own provider configuration. As a result, each resource alias maps to a different provider configurations declared in the root module:

provider "aws" {
  alias  = "usw1"
  region = "us-west-1"
}

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

module "tunnel" {
  source    = "./tunnel"
  providers = {
    aws.src = aws.usw1
    aws.dst = aws.usw2
  }
}

Non-default provider configurations are never automatically inherited, so any module that works in this manner always requires a providers argument. The documentation for the module should specify all of the provider configuration names it needs.