github.com/hugorut/terraform@v1.1.3/website/docs/language/meta-arguments/module-providers.mdx (about)

     1  ---
     2  page_title: The Module providers Meta-Argument - Configuration Language
     3  description: >-
     4    The providers meta-argument specifies which provider configurations from a
     5    parent module are available in a child module.
     6  ---
     7  
     8  # The Module `providers` Meta-Argument
     9  
    10  In a [module call](/language/modules/syntax) block, the
    11  optional `providers` meta-argument specifies which
    12  [provider configurations](/language/providers/configuration) from the parent
    13  module will be available inside the child module.
    14  
    15  ```hcl
    16  # The default "aws" configuration is used for AWS resources in the root
    17  # module where no explicit provider instance is selected.
    18  provider "aws" {
    19    region = "us-west-1"
    20  }
    21  
    22  # An alternate configuration is also defined for a different
    23  # region, using the alias "usw2".
    24  provider "aws" {
    25    alias  = "usw2"
    26    region = "us-west-2"
    27  }
    28  
    29  # An example child module is instantiated with the alternate configuration,
    30  # so any AWS resources it defines will use the us-west-2 region.
    31  module "example" {
    32    source    = "./example"
    33    providers = {
    34      aws = aws.usw2
    35    }
    36  }
    37  ```
    38  
    39  ## Default Behavior: Inherit Default Providers
    40  
    41  If the child module does not declare any [configuration aliases](/language/modules/develop/providers#provider-aliases-within-modules),
    42  the `providers` argument is optional. If you omit it, a child module inherits
    43  all of the _default_ provider configurations from its parent module. (Default
    44  provider configurations are ones that don't use the `alias` argument.)
    45  
    46  If you specify a `providers` argument, it cancels this default behavior, and the
    47  child module will _only_ have access to the provider configurations you specify.
    48  
    49  ## Usage and Behavior
    50  
    51  The value of `providers` is a map, where:
    52  
    53  - The keys are the provider configuration names used inside the child module.
    54  - The values are provider configuration names from the parent module.
    55  
    56  Both keys and values should be unquoted references to provider configurations.
    57  For default configurations, this is the local name of the provider; for
    58  alternate configurations, this is a `<PROVIDER>.<ALIAS>` reference.
    59  
    60  Within a child module, resources are assigned to provider configurations as
    61  normal — either Terraform chooses a default based on the name of the resource
    62  type, or the resource specifies an alternate configuration with the `provider`
    63  argument. If the module receives a `providers` map when it's called, the
    64  provider configuration names used within the module are effectively remapped to
    65  refer the specified configurations from the parent module.
    66  
    67  ## When to Specify Providers
    68  
    69  There are two main reasons to use the `providers` argument:
    70  
    71  - Using different default provider configurations for a child module.
    72  - Configuring a module that requires multiple configurations of the same provider.
    73  
    74  ### Changing Default Provider Configurations
    75  
    76  Most re-usable modules only use default provider configurations, which they can
    77  automatically inherit from their caller when `providers` is omitted.
    78  
    79  However, in Terraform configurations that use multiple configurations of the
    80  same provider, you might want some child modules to use the default provider
    81  configuration and other ones to use an alternate. (This usually happens when
    82  using one configuration to manage resources in multiple different regions of the
    83  same cloud provider.)
    84  
    85  By using the `providers` argument (like in the code example above), you can
    86  accommodate this without needing to edit the child module. Although the code
    87  within the child module always refers to the default provider configuration, the
    88  actual configuration of that default can be different for each instance.
    89  
    90  ### Modules With Alternate Provider Configurations
    91  
    92  In rare cases, a single re-usable module might require multiple configurations
    93  of the same provider. For example, a module that configures connectivity between
    94  networks in two AWS regions is likely to need both a source and a destination
    95  region. In that case, the root module may look something like this:
    96  
    97  ```hcl
    98  provider "aws" {
    99    alias  = "usw1"
   100    region = "us-west-1"
   101  }
   102  
   103  provider "aws" {
   104    alias  = "usw2"
   105    region = "us-west-2"
   106  }
   107  
   108  module "tunnel" {
   109    source    = "./tunnel"
   110    providers = {
   111      aws.src = aws.usw1
   112      aws.dst = aws.usw2
   113    }
   114  }
   115  ```
   116  
   117  Non-default provider configurations are never automatically inherited, so any
   118  module that works like this will always need a `providers` argument. The
   119  documentation for the module should specify all of the provider configuration
   120  names it needs.
   121  
   122  ## More Information for Module Developers
   123  
   124  For more details and guidance about working with providers inside a re-usable
   125  child module, see
   126  [Module Development: Providers Within Modules](/language/modules/develop/providers).