344 lines
17 KiB
Markdown
344 lines
17 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Provider Registry Protocol"
|
|
sidebar_current: "docs-internals-provider-registry-protocol"
|
|
description: |-
|
|
The provider registry protocol is implemented by a host intending to be the
|
|
origin host for one or more Terraform providers, specifying which providers
|
|
are available and where to find their distribution packages.
|
|
---
|
|
|
|
# Provider Registry Protocol
|
|
|
|
-> Third-party provider registries are supported only in Terraform CLI 0.13 and later. Prior versions do not support this protocol.
|
|
|
|
The provider registry protocol is what Terraform CLI uses to discover metadata
|
|
about providers available for installation and to locate the distribution
|
|
packages for a selected provider.
|
|
|
|
The primary implementation of this protocol is the public
|
|
[Terraform Registry](https://registry.terraform.io/) at `registry.terraform.io`.
|
|
By writing and deploying your own implementation of this protocol, you can
|
|
create a separate _origin registry_ to distribute your own providers, as an
|
|
alternative to publishing them on the public Terraform Registry.
|
|
|
|
This page describes the provider _registry_ protocol, which is the protocol
|
|
for finding providers available for installation. It _doesn't_ describe the
|
|
API that provider plugins themselves implement to serve requests from Terraform
|
|
CLI at runtime. For more information on the provider API, see the Terraform
|
|
SDK documentation.
|
|
|
|
The public Terraform Registry implements a superset of the API described on
|
|
this page, in order to capture additional information used in the registry UI.
|
|
Third-party implementations should not include those extensions because they
|
|
may change in future without notice.
|
|
|
|
## Provider Addresses
|
|
|
|
Each Terraform provider has an associated address which uniquely identifies it
|
|
within Terraform. A provider address has the syntax `hostname/namespace/type`,
|
|
where:
|
|
|
|
* `hostname` is the registry host that the provider is considered to have
|
|
originated from, and the default location Terraform will consult for
|
|
information about the provider
|
|
[unless overridden in the CLI configuration](/docs/cli/config/config-file.html#provider-installation).
|
|
* `namespace` is the name of a namespace, unique on a particular hostname, that
|
|
can contain one or more providers that are somehow related. On the public
|
|
Terraform Registry the "namespace" represents the organization that is
|
|
packaging and distributing the provider.
|
|
* `type` is the provider type, like "azurerm", "aws", "google", "dns", etc.
|
|
A provider type is unique within a particular hostname and namespace.
|
|
|
|
The `hostname/` portion of a provider address (including its slash delimiter)
|
|
is optional, and if omitted defaults to `registry.terraform.io/`.
|
|
|
|
For example:
|
|
|
|
* `hashicorp/aws` is a shorthand for `registry.terraform.io/hashicorp/aws`,
|
|
which is the official AWS provider published by HashiCorp.
|
|
* `example/foo` is a shorthand for `registry.terraform.io/example/foo`, which
|
|
is a hypothetical third-party provider published on the public
|
|
Terraform Registry.
|
|
* `example.com/bar/baz` is a hypothetical third-party provider published at a
|
|
third-party provider registry on `example.com`.
|
|
|
|
If you intend only to share a provider you've developed for use by all
|
|
Terraform users, please consider publishing it into the public
|
|
[Terraform Registry](https://registry.terraform.io/), which will make your
|
|
provider discoverable. You only need to implement this provider registry
|
|
protocol if you wish to publish providers whose addresses include a different
|
|
hostname that is under your control.
|
|
|
|
Terraform uses the full address (after normalization to always include a
|
|
hostname) as its global identifier for providers internally, and so it's
|
|
important to note that re-uploading the `hashicorp/azurerm` provider into
|
|
another namespace or publishing it on a different hostname will cause Terraform
|
|
to see it as an entirely separate provider that will _not_ be usable by modules
|
|
that declare a dependency on `hashicorp/azurerm`. If your goal is to create
|
|
an alternative local distribution source for an existing provider -- that is,
|
|
a _mirror_ of the provider -- refer to
|
|
[the provider installation method configuration](/docs/cli/config/config-file.html#provider-installation)
|
|
instead.
|
|
|
|
## Provider Versions
|
|
|
|
Each distinct provider address has associated with it a set of versions, each
|
|
of which has an associated version number. Terraform assumes version numbers
|
|
follow the [Semantic Versioning 2.0](https://semver.org/) conventions, with
|
|
the schema and behavior of the provider as documented from the perspective of
|
|
an end-user of Terraform serving as the "public API".
|
|
|
|
All available versions for a particular provider address are considered to be
|
|
the same provider by Terraform. Each Terraform configuration selects only one
|
|
version of each provider for use in the entire configuration, so the version
|
|
constraints across all modules are considered together for the purposes of
|
|
version selection.
|
|
|
|
## Service Discovery
|
|
|
|
The providers protocol begins with Terraform CLI using
|
|
[Terraform's remote service discovery protocol](./remote-service-discovery.html),
|
|
with the hostname in the provider address acting as the "User-facing Hostname".
|
|
|
|
The service identifier for the provider registry protocol is `providers.v1`.
|
|
Its associated string value is the base URL for the relative URLs defined in
|
|
the sections that follow.
|
|
|
|
For example, the service discovery document for a host that _only_ implements
|
|
the provider registry protocol might contain the following:
|
|
|
|
```json
|
|
{
|
|
"providers.v1": "/terraform/providers/v1/"
|
|
}
|
|
```
|
|
|
|
If the given URL is a relative URL then Terraform will interpret it as relative
|
|
to the discovery document itself. The specific provider registry protocol
|
|
endpoints are defined as URLs relative to the given base URL, and so the
|
|
specified base URL should generally end with a slash to ensure that those
|
|
relative paths will be resolved as expected.
|
|
|
|
The following sections describe the various operations that a provider
|
|
registry must implement to be compatible with Terraform CLI's provider
|
|
installer. The indicated URLs are all relative to the URL resulting from
|
|
service discovery, as described above. We use the current URLs on
|
|
Terraform Registry as working examples, assuming that the caller already
|
|
performed service discovery on `registry.terraform.io` to learn the base URL.
|
|
|
|
The URLs are shown with the convention that a path portion with a colon `:`
|
|
prefix is a placeholder for a dynamically-selected value, while all other
|
|
path portions are literal. For example, in `:namespace/:type/versions`,
|
|
the first two path portions are placeholders while the third is literally
|
|
the string "versions".
|
|
|
|
## List Available Versions
|
|
|
|
This operation determines which versions are currently available for a
|
|
particular provider.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|-----------------------------|--------------------|
|
|
| `GET` | `:namespace/:type/versions` | `application/json` |
|
|
|
|
### Parameters
|
|
|
|
* `namespace` (required): the namespace portion of the address of the requested
|
|
provider.
|
|
* `type` (required): the type portion of the address of the requested provider.
|
|
|
|
### Sample Request
|
|
|
|
```
|
|
curl 'https://registry.terraform.io/v1/providers/hashicorp/random/versions'
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"versions": [
|
|
{
|
|
"version": "2.0.0",
|
|
"protocols": ["4.0", "5.1"],
|
|
"platforms": [
|
|
{"os": "darwin", "arch": "amd64"},
|
|
{"os": "linux", "arch": "amd64"},
|
|
{"os": "linux", "arch": "arm"},
|
|
{"os": "windows", "arch": "amd64"}
|
|
]
|
|
},
|
|
{
|
|
"version": "2.0.1",
|
|
"protocols": ["5.2"],
|
|
"platforms": [
|
|
{"os": "darwin", "arch": "amd64"},
|
|
{"os": "linux", "arch": "amd64"},
|
|
{"os": "linux", "arch": "arm"},
|
|
{"os": "windows", "arch": "amd64"}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Response Properties
|
|
|
|
A successful result is a JSON object containing a single property `versions`.
|
|
`versions` is an array of objects that each describe one available version,
|
|
with the following properties:
|
|
|
|
* `version` (required): the version number this object is describing, using
|
|
the semantic versioning string notation. `version` must be unique across
|
|
all objects in the response.
|
|
* `protocols` (recommended): an array of Terraform provider API versions that
|
|
this version supports, each given in `MAJOR.MINOR` format where each major
|
|
version appears only once and the given minor version is the highest minor
|
|
version supported. For example, `5.1` means that the provider supports both
|
|
protocol `5.0` and protocol `5.1`.
|
|
|
|
Terraform uses this information, when available, to provide hints to users
|
|
about upgrading or downgrading their version of a particular provider to
|
|
work with their current version of Terraform, if their currently-selected
|
|
versions are not compatible.
|
|
|
|
Which API versions are supported is, for most providers, decided by which
|
|
version of the Terraform SDK they are built against. Consult the Terraform
|
|
SDK documentation for more information.
|
|
|
|
Only Terraform 0.13 and later support third-party provider registries and
|
|
that Terraform version requires API version `5.0` or later, so in practice
|
|
it isn't useful to list major versions 4 or earlier in a third-party
|
|
provider registry.
|
|
* `platforms` (recommended): an array of objects describing platforms that have
|
|
packages available for this version.
|
|
|
|
Terraform may use this information, when available, to provide hints to
|
|
users about upgrading or downgrading their version of a particular provider
|
|
for compatibility with their current platform.
|
|
|
|
The `platforms` objects have properties `os` and `arch`, whose values match
|
|
the properties of the same name in the response to
|
|
[Find a Provider Package](#find-a-provider-package).
|
|
|
|
Return `404 Not Found` to signal that the registry does not have a provider
|
|
with the given namespace and type.
|
|
|
|
## Find a Provider Package
|
|
|
|
This operation returns the download URL of and associated metadata about the
|
|
distribution package for a particular version of a provider for a particular
|
|
operating system and architecture.
|
|
|
|
Terraform CLI uses this operation after it has selected the newest available
|
|
version matching the configured version constraints, in order to find the zip
|
|
archive containing the plugin itself.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|------------------------------------------------|--------------------|
|
|
| `GET` | `:namespace/:type/:version/download/:os/:arch` | `application/json` |
|
|
|
|
### Parameters
|
|
|
|
* `namespace` (required): the namespace portion of the address of the requested
|
|
provider.
|
|
* `type` (required): the type portion of the address of the requested provider.
|
|
* `version` (required): the version selected to download. This will exactly
|
|
match one of the version strings returned from a previous call to
|
|
[List Available Versions](#list-available-versions).
|
|
* `os` (required): a keyword identifying the operating system that the returned
|
|
package should be compatible with, like "linux" or "darwin".
|
|
* `arch` (required): a keyword identifying the CPU architecture that the
|
|
returned package should be compatible with, like "amd64" or "arm".
|
|
|
|
### Sample Request
|
|
|
|
```
|
|
curl 'https://registry.terraform.io/v1/providers/hashicorp/random/2.0.0/download/linux/amd64'
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"protocols": ["4.0", "5.1"],
|
|
"os": "linux",
|
|
"arch": "amd64",
|
|
"filename": "terraform-provider-random_2.0.0_linux_amd64.zip",
|
|
"download_url": "https://releases.hashicorp.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_linux_amd64.zip",
|
|
"shasums_url": "https://releases.hashicorp.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_SHA256SUMS",
|
|
"shasums_signature_url": "https://releases.hashicorp.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_SHA256SUMS.sig",
|
|
"shasum": "5f9c7aa76b7c34d722fc9123208e26b22d60440cb47150dd04733b9b94f4541a",
|
|
"signing_keys": {
|
|
"gpg_public_keys": [
|
|
{
|
|
"key_id": "51852D87348FFC4C",
|
|
"ascii_armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1\n\nmQENBFMORM0BCADBRyKO1MhCirazOSVwcfTr1xUxjPvfxD3hjUwHtjsOy/bT6p9f\nW2mRPfwnq2JB5As+paL3UGDsSRDnK9KAxQb0NNF4+eVhr/EJ18s3wwXXDMjpIifq\nfIm2WyH3G+aRLTLPIpscUNKDyxFOUbsmgXAmJ46Re1fn8uKxKRHbfa39aeuEYWFA\n3drdL1WoUngvED7f+RnKBK2G6ZEpO+LDovQk19xGjiMTtPJrjMjZJ3QXqPvx5wca\nKSZLr4lMTuoTI/ZXyZy5bD4tShiZz6KcyX27cD70q2iRcEZ0poLKHyEIDAi3TM5k\nSwbbWBFd5RNPOR0qzrb/0p9ksKK48IIfH2FvABEBAAG0K0hhc2hpQ29ycCBTZWN1\ncml0eSA8c2VjdXJpdHlAaGFzaGljb3JwLmNvbT6JATgEEwECACIFAlMORM0CGwMG\nCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEFGFLYc0j/xMyWIIAIPhcVqiQ59n\nJc07gjUX0SWBJAxEG1lKxfzS4Xp+57h2xxTpdotGQ1fZwsihaIqow337YHQI3q0i\nSqV534Ms+j/tU7X8sq11xFJIeEVG8PASRCwmryUwghFKPlHETQ8jJ+Y8+1asRydi\npsP3B/5Mjhqv/uOK+Vy3zAyIpyDOMtIpOVfjSpCplVRdtSTFWBu9Em7j5I2HMn1w\nsJZnJgXKpybpibGiiTtmnFLOwibmprSu04rsnP4ncdC2XRD4wIjoyA+4PKgX3sCO\nklEzKryWYBmLkJOMDdo52LttP3279s7XrkLEE7ia0fXa2c12EQ0f0DQ1tGUvyVEW\nWmJVccm5bq25AQ0EUw5EzQEIANaPUY04/g7AmYkOMjaCZ6iTp9hB5Rsj/4ee/ln9\nwArzRO9+3eejLWh53FoN1rO+su7tiXJA5YAzVy6tuolrqjM8DBztPxdLBbEi4V+j\n2tK0dATdBQBHEh3OJApO2UBtcjaZBT31zrG9K55D+CrcgIVEHAKY8Cb4kLBkb5wM\nskn+DrASKU0BNIV1qRsxfiUdQHZfSqtp004nrql1lbFMLFEuiY8FZrkkQ9qduixo\nmTT6f34/oiY+Jam3zCK7RDN/OjuWheIPGj/Qbx9JuNiwgX6yRj7OE1tjUx6d8g9y\n0H1fmLJbb3WZZbuuGFnK6qrE3bGeY8+AWaJAZ37wpWh1p0cAEQEAAYkBHwQYAQIA\nCQUCUw5EzQIbDAAKCRBRhS2HNI/8TJntCAClU7TOO/X053eKF1jqNW4A1qpxctVc\nz8eTcY8Om5O4f6a/rfxfNFKn9Qyja/OG1xWNobETy7MiMXYjaa8uUx5iFy6kMVaP\n0BXJ59NLZjMARGw6lVTYDTIvzqqqwLxgliSDfSnqUhubGwvykANPO+93BBx89MRG\nunNoYGXtPlhNFrAsB1VR8+EyKLv2HQtGCPSFBhrjuzH3gxGibNDDdFQLxxuJWepJ\nEK1UbTS4ms0NgZ2Uknqn1WRU1Ki7rE4sTy68iZtWpKQXZEJa0IGnuI2sSINGcXCJ\noEIgXTMyCILo34Fa/C6VCm2WBgz9zZO8/rHIiQm1J5zqz0DrDwKBUM9C\n=LYpS\n-----END PGP PUBLIC KEY BLOCK-----",
|
|
"trust_signature": "",
|
|
"source": "HashiCorp",
|
|
"source_url": "https://www.hashicorp.com/security.html"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Response Properties
|
|
|
|
A successful result is a JSON object with the following properties:
|
|
|
|
* `protocols` (required): an array of Terraform provider API versions that
|
|
the provider supports, in the same format as for
|
|
[List Available Versions](#list-available-versions).
|
|
|
|
While this property is optional when listing available options, it is
|
|
_required_ for describing an individual provider package so that Terraform
|
|
CLI can avoid downloading a package that will not be compatible with it.
|
|
|
|
* `os` (required): this must currently echo back the `os` parameter from the
|
|
request. Other possibilities may come in later versions of this protocol.
|
|
|
|
* `arch` (required): this must currently echo back the `arch` parameter from the
|
|
request. Other possibilities may come in later versions of this protocol.
|
|
|
|
* `filename` (required): the filename for this provider's zip archive as
|
|
recorded in the "shasums" document, so that Terraform CLI can determine which
|
|
of the given checksums should be used for this specific package.
|
|
|
|
* `download_url` (required): a URL from which Terraform can retrieve the
|
|
provider's zip archive. If this is a relative URL then it will be resolved
|
|
relative to the URL that returned the containing JSON object.
|
|
|
|
* `shasums_url` (required): a URL from which Terraform can retrieve a text
|
|
document recording expected SHA256 checksums for this package and possibly
|
|
other packages for the same provider version on other platforms.
|
|
|
|
The indicated document must be in the format generated by the `sha256`
|
|
command available on many Unix systems, with one entry recording the
|
|
same filename given in the `filename` property (case sensitive).
|
|
|
|
* `shasums_signature_url` (required): a URL from which Terraform can retrieve
|
|
a binary, detached GPG signature for the document at `shasums_url`, signed
|
|
by one of the keys indicated in the `signing_keys` property.
|
|
|
|
* `signing_keys` (required): an object describing signing keys for this
|
|
provider package, one of which must have been used to produce the signature
|
|
at `shasums_signature_url`. The object has the following nested properties:
|
|
|
|
* `gpg_public_keys` (required): an array of objects, each describing one
|
|
GPG signing key that is allowed to sign the checksums for this provider
|
|
version. At least one element must be included, representing the key that
|
|
produced the signature at `shasums_signature_url`. These objects have
|
|
the following nested properties:
|
|
|
|
* `key_id` (required): uppercase-hexadecimal-formatted ID for this GPG key
|
|
|
|
* `ascii_armor` (required): an "ascii-armor" encoding of the **public key**
|
|
associated with this GPG key.
|
|
|
|
Return `404 Not Found` to signal that the given provider version isn't
|
|
available for the requested operating system and/or architecture. Terraform
|
|
CLI will only attempt to download versions that it has previously seen in
|
|
response to [List Available Versions](#list-available-versions).
|