Add documentation for provider_meta.

Author: paddycarver

website/docs/configuration/terraform.html.md

@@ -121,3 +121,11 @@ Re-usable modules should constrain only the minimum allowed version, such
 as `>= 1.0.0`. This specifies the earliest version that the module is
 compatible with while leaving the user of the module flexibility to upgrade
 to newer versions of the provider without altering the module.
+
+## Passing Metadata to Providers
+
+The `terraform` block can have a nested `provider_meta` block for each
+provider a module is using, if the provider defines a schema for it. This
+allows the provider to receive module-specific information. No interpolations
+are performed on this block. For more information, see the
+[`provider_meta` page](/docs/internals/provider-meta.html).

website/docs/internals/provider-meta.html.md

@@ -0,0 +1,71 @@
+---
+layout: "docs"
+page_title: "Provider Metadata"
+sidebar_current: "docs-internals-provider-meta"
+description: |-
+  For advanced use cases, modules can provide some pre-defined metadata for providers.
+---
+
+# Provider Metadata
+
+In some situations it's beneficial for a provider to offer an interface
+through which modules can pass it information unrelated to the resources
+in the module, but scoped on a per-module basis. The provider metadata
+functionality allows a provider to do this in a straightforward way.
+
+~> **Advanced Topic!** This page covers technical details
+of Terraform. You don't need to understand these details to
+effectively use Terraform. The details are documented here for
+module authors and provider developers working on advanced
+functionality.
+
+~> **Experimental Feature!** This functionality is still considered
+experimental, and anyone taking advantage of it should [coordinate
+with the Terraform team](https://github.com/hashicorp/terraform/issues/new)
+to help the team understand how the feature is being used and to make
+sure their use case is taken into account as the feature develops.
+
+## Defining the Schema
+
+Before a provider can receive information from a module, the provider
+must strictly define the data it can accept. You can do this by setting
+the `ProviderMeta` property on your `schema.Provider` struct. Its value
+functions similarly to the provider config: a map of strings to the
+`schema.Schema` describing the values those strings accept.
+
+## Using the Data
+
+When Terraform calls your provider, you can use the `schema.ResourceData`
+that your `Create`, `Read`, and `Update` functions already use to get
+access to the provider metadata being passed. First define a struct
+that matches your schema, then call the `GetProviderSchema` method on
+your `schema.ResourceData`, passing a pointer to a variable of that type.
+The variable will be populated with the provider metadata, and will return
+an error if there was an issue with parsing the data into the struct.
+
+## Specifying Data in Modules
+
+To include data in your modules, create a `provider_meta` nested block under
+your module's `terraform` block, with the name of the provider it's trying
+to pass information to:
+
+```hcl
+terraform {
+  provider_meta "my-provider" {
+    hello = "world"
+  }
+}
+```
+
+The `provider_meta` block must match the schema the provider has defined.
+
+## Versioning Your Modules
+
+Any module taking advantage of this functionality must make sure that the
+provider metadata supplied matches the schema defined in the provider, and
+that the version of Terraform that is being run has support for the provider
+metadata functionality. It's therefore recommended that any module taking
+advantage of this functionality should specify a minimum Terraform version of
+0.12.14 or higher, and a minimum version of each of the providers it specifies
+metadata as the first version the schema being used was supported by the
+provider.

website/layouts/docs.erb

@@ -450,6 +450,10 @@
           <li<%= sidebar_current("docs-internals-plugins") %>>
             <a href="/docs/internals/internal-plugins.html">Internal Plugins</a>
           </li>
+
+          <li<%= sidebar_current("docs-internals-provider-meta") %>>
+            <a href="/docs/internals/provider-meta.html">Provider Metadata</a>
+          </li>
         </ul>
       </li>