draft of providers m-a ref

Author: trujillo-adam

content/terraform/v1.13.x/data/language-nav-data.json

@@ -373,9 +373,17 @@
         "title": "for_each",
         "path": "meta-arguments/for_each"
       },
+      {
+        "title": "lifecycle",
+        "path": "meta-arguments/lifecycle"
+      },
       {
         "title": "provider",
         "path": "meta-arguments/provider"
+      },
+      {
+        "title": "providers",
+        "path": "meta-arguments/providers"
       }
     ]
   },

content/terraform/v1.13.x/docs/language/block/module.mdx

@@ -453,18 +453,7 @@ module "<LABEL>" {
 }
 ```
 
-By default, a child module inherits the default provider configuration from its parent module, but you can create multiple provider configurations and use an alternate configuration for each module. Because a module is collection of different resources, some modules also let you specify an alternate configuration for different resources in the module. Refer to the module documentation for details.
-
-The `providers` argument is a map of key-value pairs that reference provider configurations. The key references the provider configuration name used in the child module. Refer to the module documentation for details on how to define keys. The value references the provider configuration name from the parent module. Use the `<PROVIDER>.<ALIAS>` syntax to reference alternate provider configurations in key values.
-
-The `providers` argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to [Meta-arguments](/terraform/language/meta-arguments) for more information.
-
-#### Summary
-
-- Data type: Map.
-- Default: None.
-- Example: [Apply different provider configurations for module resources](#apply-different-provider-configurations-for-module-resource)
-
+`providers` is a **meta-argument**. Meta-arguments are built into the Terraform language and control how Terraform creates resources. Refer to the [`providers` reference](/terraform/language/meta-arguments/providers) for details about how the argument works.
 
 ### `depends_on`
 
@@ -731,26 +720,3 @@ module "vpc" {
 }
 ```
 
-### Apply different provider configurations for module resources
-
-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:
-
-```hcl
-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
-  }
-}
-```

content/terraform/v1.13.x/docs/language/meta-arguments/index.mdx

@@ -40,27 +40,7 @@ By default, Terraform determines the local name of the provider from the first w
 
 ## `providers`
 
-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.
-
-Some modules may contain resources that require different providers. As a result, you can specify alternate configurations for each provider supported by the module. Refer to the module documentation for details about the providers it supports.
-
-When you add a `providers` argument, child modules only have access to the provider configurations you specify. Use the `providers` argument in the following scenarios:
-
-- To use an alternate provider configuration for a child module.
-- To configure a module that requires multiple configurations of the same provider.
-
-### Examples
-
-- [Apply different provider configurations](/terraform/language/block/module#apply-different-provider-configurations-for-module-resources)  for module resources
-
-### Guidance
-
-- [Provider Aliases Within Modules](/terraform/language/modules/develop/providers#provider-aliases-within-modules)
-
-### Reference
-
-- [`providers` argument in `module` blocks](/terraform/language/block/module#providers)
-- [Providers module development documentation](/terraform/language/modules/develop/providers)
+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. Refer to the [`providers` reference](/terraform/language/meta-arguments/providers) for details.
 
 ## `lifecycle`
 

content/terraform/v1.13.x/docs/language/meta-arguments/provider.mdx

@@ -114,28 +114,4 @@ import {
 resource "aws_instance" "web" {
   # ...
 }
-```
-
-### Apply different provider configurations for module resources
-
-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:
-
-```hcl
-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
-  }
-}
 ```

content/terraform/v1.13.x/docs/language/meta-arguments/providers.mdx

@@ -0,0 +1,143 @@
+---
+page_title: providers meta-argument reference
+description: Learn how the `providers` meta-argument works in Terraform configuration.
+---
+
+# `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](/terraform/language/module/syntax), you can add the optional `providers` meta-argument to specify which [provider configurations](/terraform/language/modules/configuration) 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.
+
+
+```hcl
+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`](/terraform/language/modules/develop/providers#provider-aliases-within-modules). 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](/terraform/language/modules/develop/providers).
+
+## Supported constructs
+
+You can use `providers` in the following Terraform configuration blocks:
+
+- [`module` blocks](/terraform/language/block/module)
+
+### Example use cases
+
+The following use cases describe common patterns for the `providers` argument.
+
+### Apply different provider configurations for module resources
+
+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:
+
+```hcl
+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
+  }
+}
+```
+
+### 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. The following example shows possible root module configuration for this use case:
+
+```hcl
+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.