github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/internals/provider-meta.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Provider Metadata"
     4  sidebar_current: "docs-internals-provider-meta"
     5  description: |-
     6    For advanced use cases, modules can provide some pre-defined metadata for providers.
     7  ---
     8  
     9  # Provider Metadata
    10  
    11  In some situations it's beneficial for a provider to offer an interface
    12  through which modules can pass it information unrelated to the resources
    13  in the module, but scoped on a per-module basis.
    14  
    15  Provider Metadata allows a provider to declare metadata fields it expects,
    16  which individual modules can then populate independently of any provider
    17  configuration. While provider configurations are often shared between modules,
    18  provider metadata is always module-specific.
    19  
    20  Provider Metadata is intended primarily for the situation where an official
    21  module is developed by the same vendor that produced the provider it is
    22  intended to work with, to allow the vendor to indirectly obtain usage
    23  statistics for each module via the provider. For that reason, this
    24  documentation is presented from the perspective of the provider developer
    25  rather than the module developer.
    26  
    27  ~> **Advanced Topic!** This page covers technical details
    28  of Terraform. You don't need to understand these details to
    29  effectively use Terraform. The details are documented here for
    30  module authors and provider developers working on advanced
    31  functionality.
    32  
    33  ~> **Experimental Feature!** This functionality is still considered
    34  experimental, and anyone taking advantage of it should [coordinate
    35  with the Terraform team](https://github.com/hashicorp/terraform/issues/new)
    36  to help the team understand how the feature is being used and to make
    37  sure their use case is taken into account as the feature develops.
    38  
    39  ## Defining the Schema
    40  
    41  Before a provider can receive information from a module, the provider
    42  must strictly define the data it can accept. You can do this by setting
    43  the `ProviderMeta` property on your `schema.Provider` struct. Its value
    44  functions similarly to the provider config: a map of strings to the
    45  `schema.Schema` describing the values those strings accept.
    46  
    47  ## Using the Data
    48  
    49  When Terraform calls your provider, you can use the `schema.ResourceData`
    50  that your `Create`, `Read`, and `Update` functions already use to get
    51  access to the provider metadata being passed. First define a struct
    52  that matches your schema, then call the `GetProviderSchema` method on
    53  your `schema.ResourceData`, passing a pointer to a variable of that type.
    54  The variable will be populated with the provider metadata, and will return
    55  an error if there was an issue with parsing the data into the struct.
    56  
    57  ## Specifying Data in Modules
    58  
    59  To include data in your modules, create a `provider_meta` nested block under
    60  your module's `terraform` block, with the name of the provider it's trying
    61  to pass information to:
    62  
    63  ```hcl
    64  terraform {
    65    provider_meta "my-provider" {
    66      hello = "world"
    67    }
    68  }
    69  ```
    70  
    71  The `provider_meta` block must match the schema the provider has defined.
    72  
    73  ## Versioning Your Modules
    74  
    75  Any module taking advantage of this functionality must make sure that the
    76  provider metadata supplied matches the schema defined in the provider, and
    77  that the version of Terraform that is being run has support for the provider
    78  metadata functionality. It's therefore recommended that any module taking
    79  advantage of this functionality should specify a minimum Terraform version of
    80  0.13.0 or higher, and a minimum version of each of the providers it specifies
    81  metadata as the first version the schema being used was supported by the
    82  provider.