From ee16912941ce9230624eb1277ebd353a8cf3f226 Mon Sep 17 00:00:00 2001
From: Paddy Carver <paddy@carvers.co>
Date: Fri, 1 Nov 2019 00:26:42 -0700
Subject: [PATCH] Add documentation for provider_meta.

---
 website/docs/configuration/terraform.html.md |  8 +++
 website/docs/internals/provider-meta.html.md | 71 ++++++++++++++++++++
 website/layouts/docs.erb                     |  4 ++
 3 files changed, 83 insertions(+)
 create mode 100644 website/docs/internals/provider-meta.html.md

diff --git a/website/docs/configuration/terraform.html.md b/website/docs/configuration/terraform.html.md
index 16209970e4c5..c7036bd7e693 100644
--- a/website/docs/configuration/terraform.html.md
+++ b/website/docs/configuration/terraform.html.md
@@ -129,3 +129,11 @@ to newer versions of the provider without altering the module.
 Root modules should use a `~>` constraint to set both a lower and upper bound
 on versions for each provider they depend on, as described in
 [Provider Versions](providers.html#provider-versions).
+
+## 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).
diff --git a/website/docs/internals/provider-meta.html.md b/website/docs/internals/provider-meta.html.md
new file mode 100644
index 000000000000..1ef44aac3cf7
--- /dev/null
+++ b/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.
diff --git a/website/layouts/docs.erb b/website/layouts/docs.erb
index f1197097fce3..23278af7172e 100644
--- a/website/layouts/docs.erb
+++ b/website/layouts/docs.erb
@@ -456,6 +456,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>