website: Remove registry docs (adopted into terraform-website)

The Registry is a web service whose behavior isn't directly tied to Terraform
core's release cycle; therefore, its docs should be decoupled from that release
cycle as well.

https://github.com/hashicorp/terraform-website/pull/1517 adopts the registry
docs into hashicorp/terraform-website, which already hosts several other
corpuses of documentation that aren't tied to Terraform core's version (like
Terraform Cloud, Terraform Enterprise, and Extending Terraform). Once that PR is
merged, we should remove the registry docs from this repository to avoid
confusing anyone.
This commit is contained in:
Nick Fagerlund 2020-11-18 11:12:35 -08:00
parent db82b80c9d
commit 2014e8ef64
22 changed files with 0 additions and 1593 deletions

View File

@ -1,771 +0,0 @@
---
layout: "registry"
page_title: "Terraform Registry - HTTP API"
sidebar_current: "docs-registry-api"
description: |-
The /api endpoints list modules according to some criteria.
---
# HTTP API
When downloading modules from registry sources such as the public
[Terraform Registry](https://registry.terraform.io/), Terraform CLI expects
the given hostname to support
[the module registry protocol](/docs/internals/module-registry-protocol.html),
which is the minimal API required for Terraform CLI to successfully retrieve
a module.
The public Terraform Registry and the private registry included in Terraform
Cloud and Terraform Enterprise implement a superset of that minimal module
registry API to support additional use-cases such as searching for modules
across the whole registry, retrieving documentation and schemas for modules,
and so on.
This page describes the extended API implemented by the official module
registry implementations, and is aimed at those intending to build clients
to work with registry data. Third-party implementations of the registry
protocol are not required to implement these extensions. If you intend to
implement your own module registry, please refer to
[the module registry protocol](/docs/internals/module-registry-protocol.html)
instead.
Terraform Registry also has some additional internal API endpoints used to
support its UI. Any endpoints or properties not documented on this page are
subject to change over time.
## Service Discovery
The hostname portion of a module source address is first passed to
[the service discovery protocol](/docs/internals/remote-service-discovery.html)
to determine if the given host has a module registry and, if so, the base
URL for its module registry endpoints.
The service identifier for this protocol is `modules.v1`, and the declared
URL should always end with a slash such that the paths shown in the following
sections can be appended to it.
For example, if discovery produces the URL `https://modules.example.com/v1/`
then this API would use full endpoint URLs like
`https://modules.example.com/v1/{namespace}/{name}/{provider}/versions`.
A module source address with no hostname is a shorthand for an address
on `registry.terraform.io`. You can perform service discovery on that hostname
to find the public Terraform Registry's module API endpoints.
## Base URL
The example request URLs shown in this document are for the public [Terraform
Registry](https://registry.terraform.io), and use its API `<base_url>` of
`https://registry.terraform.io/v1/modules/`. Note that although the base URL in
the [discovery document](#service-discovery) _may include_ a trailing slash, we
include a slash after the placeholder in the `Path`s below for clarity.
## List Modules
These endpoints list modules according to some criteria.
| Method | Path | Produces |
| ------ | ------------------------------------- | -------------------------- |
| `GET` | `<base_url>` | `application/json` |
| `GET` | `<base_url>/:namespace` | `application/json` |
### Parameters
- `namespace` `(string: <optional>)` - Restricts listing to modules published by
this user or organization. This is optionally specified as part of the URL
path.
### Query Parameters
- `offset`, `limit` `(int: <optional>)` - See [Pagination](#pagination) for details.
- `provider` `(string: <optional>)` - Limits modules to a specific provider.
- `verified` `(bool: <optional>)` - If `true`, limits results to only verified
modules. Any other value including none returns all modules _including_
verified ones.
### Sample Request
```text
$ curl 'https://registry.terraform.io/v1/modules?limit=2&verified=true'
```
### Sample Response
```json
{
"meta": {
"limit": 2,
"current_offset": 0,
"next_offset": 2,
"next_url": "/v1/modules?limit=2&offset=2&verified=true"
},
"modules": [
{
"id": "GoogleCloudPlatform/lb-http/google/1.0.4",
"owner": "",
"namespace": "GoogleCloudPlatform",
"name": "lb-http",
"version": "1.0.4",
"provider": "google",
"description": "Modular Global HTTP Load Balancer for GCE using forwarding rules.",
"source": "https://github.com/GoogleCloudPlatform/terraform-google-lb-http",
"published_at": "2017-10-17T01:22:17.792066Z",
"downloads": 213,
"verified": true
},
{
"id": "terraform-aws-modules/vpc/aws/1.5.1",
"owner": "",
"namespace": "terraform-aws-modules",
"name": "vpc",
"version": "1.5.1",
"provider": "aws",
"description": "Terraform module which creates VPC resources on AWS",
"source": "https://github.com/terraform-aws-modules/terraform-aws-vpc",
"published_at": "2017-11-23T10:48:09.400166Z",
"downloads": 29714,
"verified": true
}
]
}
```
## Search Modules
This endpoint allows searching modules.
| Method | Path | Produces |
| ------ | ------------------------------------- | -------------------------- |
| `GET` | `<base_url>/search` | `application/json` |
### Query Parameters
- `q` `(string: <required>)` - The search string. Search syntax understood
depends on registry implementation. The public registry supports basic keyword
or phrase searches.
- `offset`, `limit` `(int: <optional>)` - See [Pagination](#pagination) for details.
- `provider` `(string: <optional>)` - Limits results to a specific provider.
- `namespace` `(string: <optional>)` - Limits results to a specific namespace.
- `verified` `(bool: <optional>)` - If `true`, limits results to only verified
modules. Any other value including none returns all modules _including_
verified ones.
### Sample Request
```text
$ curl 'https://registry.terraform.io/v1/modules/search?q=network&limit=2'
```
### Sample Response
```json
{
"meta": {
"limit": 2,
"current_offset": 0,
"next_offset": 2,
"next_url": "/v1/modules/search?limit=2&offset=2&q=network"
},
"modules": [
{
"id": "zoitech/network/aws/0.0.3",
"owner": "",
"namespace": "zoitech",
"name": "network",
"version": "0.0.3",
"provider": "aws",
"description": "This module is intended to be used for configuring an AWS network.",
"source": "https://github.com/zoitech/terraform-aws-network",
"published_at": "2017-11-23T15:12:06.620059Z",
"downloads": 39,
"verified": false
},
{
"id": "Azure/network/azurerm/1.1.1",
"owner": "",
"namespace": "Azure",
"name": "network",
"version": "1.1.1",
"provider": "azurerm",
"description": "Terraform Azure RM Module for Network",
"source": "https://github.com/Azure/terraform-azurerm-network",
"published_at": "2017-11-22T17:15:34.325436Z",
"downloads": 1033,
"verified": true
}
]
}
```
## List Available Versions for a Specific Module
This is the primary endpoint for resolving module sources, returning the
available versions for a given fully-qualified module.
| Method | Path | Produces |
| ------ | ------------------------------------- | -------------------------- |
| `GET` | `<base_url>/:namespace/:name/:provider/versions` | `application/json` |
### Parameters
- `namespace` `(string: <required>)` - The user or organization the module is
owned by. This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - The name of the module.
This is required and is specified as part of the URL path.
- `provider` `(string: <required>)` - The name of the provider.
This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl https://registry.terraform.io/v1/modules/hashicorp/consul/aws/versions
```
### Sample Response
The `modules` array in the response always includes the requested module as the
first element. Other elements of this list, if present, are dependencies of the
requested module that are provided to potentially avoid additional requests to
resolve these modules.
Additional modules are not required to be provided but, when present, can be
used by Terraform to optimize the module installation process.
Each returned module has an array of available versions, which Terraform
matches against any version constraints given in configuration.
```json
{
"modules": [
{
"source": "hashicorp/consul/aws",
"versions": [
{
"version": "0.0.1",
"submodules" : [
{
"path": "modules/consul-cluster",
"providers": [
{
"name": "aws",
"version": ""
}
],
"dependencies": []
},
{
"path": "modules/consul-security-group-rules",
"providers": [
{
"name": "aws",
"version": ""
}
],
"dependencies": []
},
{
"providers": [
{
"name": "aws",
"version": ""
}
],
"dependencies": [],
"path": "modules/consul-iam-policies"
}
],
"root": {
"dependencies": [],
"providers": [
{
"name": "template",
"version": ""
},
{
"name": "aws",
"version": ""
}
]
}
}
]
}
]
}
```
## Download Source Code for a Specific Module Version
This endpoint downloads the specified version of a module for a single provider.
A successful response has no body, and includes the location from which the module
version's source can be downloaded in the `X-Terraform-Get` header. Note that
this string may contain special syntax interpreted by Terraform via
[`go-getter`](https://github.com/hashicorp/go-getter). See the [`go-getter`
documentation](https://github.com/hashicorp/go-getter#url-format) for details.
The value of `X-Terraform-Get` may instead be a relative URL, indicated by
beginning with `/`, `./` or `../`, in which case it is resolved relative to
the full URL of the download endpoint.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `<base_url>/:namespace/:name/:provider/:version/download` | `application/json` |
### Parameters
- `namespace` `(string: <required>)` - The user the module is owned by.
This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - The name of the module.
This is required and is specified as part of the URL path.
- `provider` `(string: <required>)` - The name of the provider.
This is required and is specified as part of the URL path.
- `version` `(string: <required>)` - The version of the module.
This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl -i \
https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1/download
```
### Sample Response
```text
HTTP/1.1 204 No Content
Content-Length: 0
X-Terraform-Get: https://api.github.com/repos/hashicorp/terraform-aws-consul/tarball/v0.0.1//*?archive=tar.gz
```
## List Latest Version of Module for All Providers
This endpoint returns the latest version of each provider for a module.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `<base_url>/:namespace/:name` | `application/json` |
### Parameters
- `namespace` `(string: <required>)` - The user or organization the module is
owned by. This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - The name of the module.
This is required and is specified as part of the URL path.
### Query Parameters
- `offset`, `limit` `(int: <optional>)` - See [Pagination](#pagination) for details.
### Sample Request
```text
$ curl \
https://registry.terraform.io/v1/modules/hashicorp/consul
```
### Sample Response
```json
{
"meta": {
"limit": 15,
"current_offset": 0
},
"modules": [
{
"id": "hashicorp/consul/azurerm/0.0.1",
"owner": "gruntwork-team",
"namespace": "hashicorp",
"name": "consul",
"version": "0.0.1",
"provider": "azurerm",
"description": "A Terraform Module for how to run Consul on AzureRM using Terraform and Packer",
"source": "https://github.com/hashicorp/terraform-azurerm-consul",
"published_at": "2017-09-14T23:22:59.923047Z",
"downloads": 100,
"verified": false
},
{
"id": "hashicorp/consul/aws/0.0.1",
"owner": "gruntwork-team",
"namespace": "hashicorp",
"name": "consul",
"version": "0.0.1",
"provider": "aws",
"description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
"source": "https://github.com/hashicorp/terraform-aws-consul",
"published_at": "2017-09-14T23:22:44.793647Z",
"downloads": 113,
"verified": false
}
]
}
```
## Latest Version for a Specific Module Provider
This endpoint returns the latest version of a module for a single provider.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `<base_url>/:namespace/:name/:provider` | `application/json` |
### Parameters
- `namespace` `(string: <required>)` - The user the module is owned by.
This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - The name of the module.
This is required and is specified as part of the URL path.
- `provider` `(string: <required>)` - The name of the provider.
This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl \
https://registry.terraform.io/v1/modules/hashicorp/consul/aws
```
### Sample Response
Note this response has has some fields trimmed for clarity.
```json
{
"id": "hashicorp/consul/aws/0.0.1",
"owner": "gruntwork-team",
"namespace": "hashicorp",
"name": "consul",
"version": "0.0.1",
"provider": "aws",
"description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
"source": "https://github.com/hashicorp/terraform-aws-consul",
"published_at": "2017-09-14T23:22:44.793647Z",
"downloads": 113,
"verified": false,
"root": {
"path": "",
"readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...",
"empty": false,
"inputs": [
{
"name": "ami_id",
"description": "The ID of the AMI to run in the cluster. ...",
"default": "\"\""
},
{
"name": "aws_region",
"description": "The AWS region to deploy into (e.g. us-east-1).",
"default": "\"us-east-1\""
}
],
"outputs": [
{
"name": "num_servers",
"description": ""
},
{
"name": "asg_name_servers",
"description": ""
}
],
"dependencies": [],
"resources": []
},
"submodules": [
{
"path": "modules/consul-cluster",
"readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...",
"empty": false,
"inputs": [
{
"name": "cluster_name",
"description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.",
"default": ""
},
{
"name": "ami_id",
"description": "The ID of the AMI to run in this cluster. Should be an AMI that had Consul installed and configured by the install-consul module.",
"default": ""
}
],
"outputs": [
{
"name": "asg_name",
"description": ""
},
{
"name": "cluster_size",
"description": ""
}
],
"dependencies": [],
"resources": [
{
"name": "autoscaling_group",
"type": "aws_autoscaling_group"
},
{
"name": "launch_configuration",
"type": "aws_launch_configuration"
}
]
}
],
"providers": [
"aws",
"azurerm"
],
"versions": [
"0.0.1"
]
}
```
## Get a Specific Module
This endpoint returns the specified version of a module for a single provider.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `<base_url>/:namespace/:name/:provider/:version` | `application/json` |
### Parameters
- `namespace` `(string: <required>)` - The user the module is owned by.
This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - The name of the module.
This is required and is specified as part of the URL path.
- `provider` `(string: <required>)` - The name of the provider.
This is required and is specified as part of the URL path.
- `version` `(string: <required>)` - The version of the module.
This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl \
https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1
```
### Sample Response
Note this response has has some fields trimmed for clarity.
```json
{
"id": "hashicorp/consul/aws/0.0.1",
"owner": "gruntwork-team",
"namespace": "hashicorp",
"name": "consul",
"version": "0.0.1",
"provider": "aws",
"description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer",
"source": "https://github.com/hashicorp/terraform-aws-consul",
"published_at": "2017-09-14T23:22:44.793647Z",
"downloads": 113,
"verified": false,
"root": {
"path": "",
"readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...",
"empty": false,
"inputs": [
{
"name": "ami_id",
"description": "The ID of the AMI to run in the cluster. ...",
"default": "\"\""
},
{
"name": "aws_region",
"description": "The AWS region to deploy into (e.g. us-east-1).",
"default": "\"us-east-1\""
}
],
"outputs": [
{
"name": "num_servers",
"description": ""
},
{
"name": "asg_name_servers",
"description": ""
}
],
"dependencies": [],
"resources": []
},
"submodules": [
{
"path": "modules/consul-cluster",
"readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...",
"empty": false,
"inputs": [
{
"name": "cluster_name",
"description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.",
"default": ""
},
{
"name": "ami_id",
"description": "The ID of the AMI to run in this cluster. Should be an AMI that had Consul installed and configured by the install-consul module.",
"default": ""
}
],
"outputs": [
{
"name": "asg_name",
"description": ""
},
{
"name": "cluster_size",
"description": ""
}
],
"dependencies": [],
"resources": [
{
"name": "autoscaling_group",
"type": "aws_autoscaling_group"
},
{
"name": "launch_configuration",
"type": "aws_launch_configuration"
}
]
}
],
"providers": [
"aws",
"azurerm"
],
"versions": [
"0.0.1"
]
}
```
## Download the Latest Version of a Module
This endpoint downloads the latest version of a module for a single provider.
It returns a 302 redirect whose `Location` header redirects the client to the
download endpoint (above) for the latest version.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `<base_url>/:namespace/:name/:provider/download` | `application/json` |
### Parameters
- `namespace` `(string: <required>)` - The user the module is owned by.
This is required and is specified as part of the URL path.
- `name` `(string: <required>)` - The name of the module.
This is required and is specified as part of the URL path.
- `provider` `(string: <required>)` - The name of the provider.
This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl -i \
https://registry.terraform.io/v1/modules/hashicorp/consul/aws/download
```
### Sample Response
```text
HTTP/1.1 302 Found
Location: /v1/modules/hashicorp/consul/aws/0.0.1/download
Content-Length: 70
Content-Type: text/html; charset=utf-8
<a href="/v1/modules/hashicorp/consul/aws/0.0.1/download">Found</a>.
```
## HTTP Status Codes
The API follows regular HTTP status semantics. To make implementing a complete
client easier, some details on our policy and potential future status codes are
listed below. A robust client should consider how to handle all of the
following.
- **Success:** Return status is `200` on success with a body or `204` if there
is no body data to return.
- **Redirects:** Moved or aliased endpoints redirect with a `301`. Endpoints
redirecting to the latest version of a module may redirect with `302` or
`307` to indicate that they logically point to different resources over time.
- **Client Errors:** Invalid requests will receive the relevant `4xx` status.
Except where noted below, the request should not be retried.
- **Rate Limiting:** Clients placing excessive load on the service might be
rate-limited and receive a `429` code. This should be interpreted as a sign
to slow down, and wait some time before retrying the request.
- **Service Errors:** The usual `5xx` errors will be returned for service
failures. In all cases it is safe to retry the request after receiving a
`5xx` response.
- **Load Shedding:** A `503` response indicates that the service is under load
and can't process your request immediately. As with other `5xx` errors you
may retry after some delay, although clients should consider being more
lenient with retry schedule in this case.
## Error Responses
When a `4xx` or `5xx` status code is returned. The response payload will look
like the following example:
```json
{
"errors": [
"something bad happened"
]
}
```
The `errors` key is a list containing one or more strings where each string
describes an error that has occurred.
Note that it is possible that some `5xx` errors might result in a response that
is not in JSON format above due to being returned by an intermediate proxy.
## Pagination
Endpoints that return lists of results use a common pagination format.
They accept positive integer query variables `offset` and `limit` which have the
usual SQL-like semantics. Each endpoint will have a default limit and a
default offset of `0`. Each endpoint will also apply a maximum limit,
requesting more results will just result in the maximum limit being used.
The response for a paginated result set will look like:
```json
{
"meta": {
"limit": 15,
"current_offset": 15,
"next_offset": 30,
"prev_offset": 0,
},
"<object name>": []
}
```
Note that:
- `next_offset` will only be present if there are more results available.
- `prev_offset` will only be present if not at `offset = 0`.
- `limit` is the actual limit that was applied, it may be lower than the requested limit param.
- The key for the result array varies based on the endpoint and will be the
type of result pluralized, for example `modules`.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 246 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 239 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 292 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

View File

@ -1,35 +0,0 @@
---
layout: "registry"
page_title: "Publishing Providers and Modules"
sidebar_current: "docs-registry-home"
description: |-
The Terraform Registry is a repository of providers and modules written by the Terraform community.
---
# Publishing Providers and Modules on the Terraform Registry
The [Terraform Registry](https://registry.terraform.io) is an interactive resource for discovering a wide selection of integrations (providers) and configuration packages (modules) for use with Terraform. The Registry includes solutions developed by HashiCorp, third-party vendors, and our Terraform community. Our goal with the Registry is to provide plugins to manage any infrastructure API, pre-made modules to quickly configure common infrastructure components, and examples of how to write quality Terraform code.
![screenshot: terraform registry landing page](./images/registry1.png)
The Terraform Registry is integrated [directly into Terraform](/docs/configuration/provider-requirements.html) so you can directly specify providers and modules. Anyone can publish and consume providers and modules on the public [Terraform Registry](https://registry.terraform.io). (To publish private modules within your organization, you can use a [private registry](/docs/registry/private.html) or [reference repositories and other sources directly](/docs/modules/sources.html).)
Use the navigation to the left to learn more about using the Terraform Registry.
## Navigating the Registry
The registry has a number of different categories for both modules and providers to help with navigating the large number of available options. Select a provider or module card to learn more, filter results to a [specific tier](./providers/index.html#provider-tiers-amp-namespaces), or use the search field at the top of the Registry to find what youre looking for. (Note that search supports keyboard navigation.)
![screenshot: terraform registry browse](./images/registry2.png)
## User Account
Anyone interested in publishing a provider or module can create an account and sign in to the Terraform Registry using a GitHub account. Click the "Sign-in" button, and follow the login prompts. Once you have authorized the use of your GitHub account and are signed in, you can publish both providers and modules directly from one of the repositories you manage. To learn more, see [Publishing to the Registry](/docs/registry/providers/publishing.html).
![screenshot: terraform registry sign in](./images/user-account.png)
## Getting Help
We welcome any feedback about using or publishing to the Registry. Please reach out if you have any questions or issues with the Terraform Registry by sending us an [email](mailto:terraform-registry-beta@hashicorp.com). The providers and modules in The Terraform Registry are published and maintained either directly by HashiCorp, by trusted HashiCorp partners, or by members of the Terraform community ([see tiers & namespaces](./providers/index.html#provider-tiers-amp-namespaces)). If you run into issues or have additional contributions to make to a provider or module, you can submit a GitHub issue by selecting the "Report an issue" link on the detail view:
![Provider report issue link](./images/registry-issue.png)

Binary file not shown.

Before

Width:  |  Height:  |  Size: 97 KiB

View File

@ -1,92 +0,0 @@
---
layout: "registry"
page_title: "Terraform Registry - Publishing Modules"
sidebar_current: "docs-registry-publish"
description: |-
Anyone can publish and share modules on the Terraform Registry.
---
# Publishing Modules
Anyone can publish and share modules on the [Terraform Registry](https://registry.terraform.io).
Published modules support versioning, automatically generate documentation,
allow browsing version histories, show examples and READMEs, and more. We
recommend publishing reusable modules to a registry.
Public modules are managed via Git and GitHub. Publishing a module takes only
a few minutes. Once a module is published, you can release a new version of
a module by simply pushing a properly formed Git tag.
The registry extracts information about the module from the module's source.
The module name, provider, documentation, inputs/outputs, and dependencies are
all parsed and available via the UI or API, as well as the same information for
any submodules or examples in the module's source repository.
## Requirements
The list below contains all the requirements for publishing a module:
- **GitHub.** The module must be on GitHub and must be a public repo.
This is only a requirement for the [public registry](https://registry.terraform.io).
If you're using a private registry, you may ignore this requirement.
- **Named `terraform-<PROVIDER>-<NAME>`.** Module repositories must use this
three-part name format, where `<NAME>` reflects the type of infrastructure the
module manages and `<PROVIDER>` is the main provider where it creates that
infrastructure. The `<NAME>` segment can contain additional hyphens. Examples:
`terraform-google-vault` or `terraform-aws-ec2-instance`.
- **Repository description.** The GitHub repository description is used
to populate the short description of the module. This should be a simple
one sentence description of the module.
- **Standard module structure.** The module must adhere to the
[standard module structure](/docs/modules/structure.html).
This allows the registry to inspect your module and generate documentation,
track resource usage, parse submodules and examples, and more.
- **`x.y.z` tags for releases.** The registry uses tags to identify module
versions. Release tag names must be a [semantic version](http://semver.org),
which can optionally be prefixed with a `v`. For example, `v1.0.4` and `0.9.2`.
To publish a module initially, at least one release tag must be present. Tags
that don't look like version numbers are ignored.
## Publishing a Public Module
With the requirements met, you can publish a public module by going to
the [Terraform Registry](https://registry.terraform.io) and clicking the
"Upload" link in the top navigation.
If you're not signed in, this will ask you to connect with GitHub. We only
ask for access to public repositories, since the public registry may only
publish public modules. We require access to hooks so we can register a webhook
with your repository. We require access to your email address so that we can
email you alerts about your module. We will not spam you.
The upload page will list your available repositories, filtered to those that
match the [naming convention described above](#Requirements). This is shown in
the screenshot below. Select the repository of the module you want to add and
click "Publish Module."
In a few seconds, your module will be created.
![Publish Module flow animation](/assets/images/docs/registry-publish.gif)
## Releasing New Versions
The Terraform Registry uses tags to detect releases.
Tag names must be a valid [semantic version](http://semver.org), optionally
prefixed with a `v`. Example of valid tags are: `v1.0.1` and `0.9.4`. To publish
a new module, you must already have at least one tag created.
To release a new version, create and push a new tag with the proper format.
The webhook will notify the registry of the new version and it will appear
on the registry usually in less than a minute.
If your version doesn't appear properly, you may force a sync with GitHub
by viewing your module on the registry and clicking "Resync Module"
under the "Manage Module" dropdown. This process may take a few minutes.
Please only do this if you do not see the version appear, since it will
cause the registry to resync _all versions_ of your module.

View File

@ -1,84 +0,0 @@
---
layout: "registry"
page_title: "Finding and Using Modules from the Terraform Registry"
sidebar_current: "docs-registry-use"
description: |-
The Terraform Registry makes it simple to find and use modules.
---
# Finding and Using Modules
The [Terraform Registry](https://registry.terraform.io) makes it simple to
find and use modules.
## Finding Modules
Every page on the registry has a search field for finding
modules. Enter any type of module you're looking for (examples: "vault",
"vpc", "database") and resulting modules will be listed. The search query
will look at module name, provider, and description to match your search
terms. On the results page, filters can be used further refine search results.
By default, only [verified modules](/docs/registry/modules/verified.html)
are shown in search results. Verified modules are reviewed by HashiCorp to
ensure stability and compatibility. By using the filters, you can view unverified
modules as well.
## Using Modules
The Terraform Registry is integrated directly into Terraform, so a Terraform
configuration can refer to any module published in the registry. The syntax for
specifying a registry module is `<NAMESPACE>/<NAME>/<PROVIDER>`. For example:
`hashicorp/consul/aws`.
~> **Note:** Module registry integration was added in Terraform v0.10.6, and full versioning support in v0.11.0.
When viewing a module on the registry on a tablet or desktop, usage instructions
are shown on the right side.
You can copy and paste this to get started with any module. Some modules
have required inputs you must set before being able to use the module.
```hcl
module "consul" {
source = "hashicorp/consul/aws"
version = "0.1.0"
}
```
The `terraform init` command will download and cache any modules referenced by
a configuration.
### Private Registry Module Sources
You can also use modules from a private registry, like the one provided by
Terraform Cloud. Private registry modules have source strings of the form
`<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>`. This is the same format as the
public registry, but with an added hostname prefix.
```hcl
module "vpc" {
source = "app.terraform.io/example_corp/vpc/aws"
version = "0.9.3"
}
```
Depending on the registry you're using, you might also need to configure
credentials to access modules. See your registry's documentation for details.
[Terraform Cloud's private registry is documented here.](/docs/cloud/registry/index.html)
Private registry module sources are supported in Terraform v0.11.0 and
newer.
## Module Versions
Each module in the registry is versioned. These versions syntactically must
follow [semantic versioning](http://semver.org/). In addition to pure syntax,
we encourage all modules to follow the full guidelines of semantic versioning.
Terraform since version 0.11 will resolve any provided
[module version constraints](/docs/configuration/blocks/modules/syntax.html#version) and
using them is highly recommended to avoid pulling in breaking changes.
Terraform versions after 0.10.6 but before 0.11 have partial support for the registry
protocol, but always download the latest version instead of honoring version
constraints.

View File

@ -1,26 +0,0 @@
---
layout: "registry"
page_title: "Terraform Registry - Verified Modules"
sidebar_current: "docs-registry-verified"
description: |-
Verified modules are reviewed by HashiCorp and actively maintained by contributors to stay up-to-date and compatible with both Terraform and their respective providers.
---
# Verified Modules
Verified modules are reviewed by HashiCorp and actively maintained by contributors to stay up-to-date and compatible with both Terraform and their respective providers.
The verified badge appears next to modules that are published by a verified source.
![Verified module listing](./images/registry-verified.png)
Verified modules are expected to be actively maintained by HashiCorp partners.
The verified badge isnt indicative of flexibility or feature support; very
simple modules can be verified just because they're great examples of modules.
Likewise, an unverified module could be extremely high quality and actively
maintained. An unverified module shouldn't be assumed to be poor quality, it
only means it hasn't been created by a HashiCorp partner.
When [using registry modules](/docs/registry/modules/use.html), there is no
difference between a verified and unverified module; they are used the same
way.

View File

@ -1,45 +0,0 @@
---
layout: "registry"
page_title: "Terraform Registry - Private Registry"
sidebar_current: "docs-registry-private"
description: |-
Terraform can load private modules from private registries via Terraform Cloud.
---
# Private Registries
The registry at [registry.terraform.io](https://registry.terraform.io)
only hosts public modules, but most organizations have some modules that
can't, shouldn't, or don't need to be public.
You can load private modules [directly from version control and other
sources](/docs/modules/sources.html), but those sources don't support [version
constraints](/docs/configuration/blocks/modules/syntax.html#version) or a browsable
marketplace of modules, both of which are important for enabling a
producers-and-consumers content model in a large organization.
If your organization is specialized enough that teams frequently use modules
created by other teams, you will benefit from a private module registry.
## Terraform Cloud's Private Registry
[Terraform Cloud](https://www.hashicorp.com/products/terraform)
includes a private module registry. It is available to all accounts, including free organizations.
It uses the same VCS-backed tagged release workflow as the Terraform Registry,
but imports modules from your private VCS repos (on any of Terraform Cloud's supported VCS
providers) instead of requiring public GitHub repos. You can seamlessly
reference private modules in your Terraform configurations (just include a
hostname in the module source), and Terraform Cloud's UI provides a searchable marketplace
of private modules to help your users find the code they need.
[Terraform Cloud's private module registry is documented here.](/docs/cloud/registry/index.html)
## Other Private Registries
Terraform can use versioned modules from any service that implements
[the registry API](/docs/registry/api.html).
The Terraform open source project does not provide a server implementation, but
we welcome community members to create their own private registries by following
the published protocol.

View File

@ -1,252 +0,0 @@
---
layout: "registry"
page_title: "Terraform Registry - Provider Documentation"
sidebar_current: "docs-registry-provider-docs"
description: |-
Expected document structure for publishing providers to the Terraform Registry.
---
# Provider Documentation
The [Terraform Registry][terraform-registry] displays documentation for the providers it hosts. This page describes the expected format for provider documentation.
-> In order to test how documents will render in the Terraform Registry, you can use the [Terraform Registry Doc Preview Tool](https://registry.terraform.io/tools/doc-preview).
## Publishing
The Terraform Registry publishes providers from their Git repositories, creating a version for each Git tag that matches the [Semver](https://semver.org/) versioning format. Provider documentation is published automatically as part of the provider release process.
Provider documentation is always tied to a provider version. A given version always displays the documentation from that version's Git commit, and the only way to publish updated documentation is to release a new version of the provider.
### Storage Limits
The maximum number of documents allowed for a single provider version is 1000.
Each document can contain no more than 500KB of data. Documents which exceed this limit will be truncated, and a note will be displayed in the Terraform Registry.
## Format
Provider documentation should be a directory of Markdown documents in the provider repository. Each Markdown document is rendered as a separate page. The directory should include a document for the provider index, a document for each resource and data source, and optional documents for any guides.
### Directory Structure
| Location | Filename | Description |
|-|-|-|
| `docs/` | `index.md` | Index page for the provider. |
| `docs/guides/` | `<guide>.md` | Additional documentation for guides. |
| `docs/resources/` | `<resource>.md` | Information for a Resource. Filename should not include a `<PROVIDER NAME>_` prefix. |
| `docs/data-sources/` | `<data_source>.md` | Information on a provider data source. |
-> **Note:** In order to support provider docs which have already been formatted for publishing to [terraform.io][terraform-io-providers], the Terraform Registry also supports docs in a `website/docs/` legacy directory with file extensions of `.html.markdown` or `.html.md`.
### Headers
We strongly suggest that provider docs include the following sections to help users understand how to use the provider. Create additional sections if they would enhance usability of the resource (for example, “Imports” or “Customizable Timeouts”).
#### Index Headers
# <provider> Provider
Summary of what the provider is for, including use cases and links to
app/service documentation.
## Example Usage
```hcl
// Code block with an example of how to use this provider.
```
## Argument Reference
* List any arguments for the provider block.
#### Resource/Data Source Headers
# <resource name> Resource/Data Source
Description of what this resource does, with links to official
app/service documentation.
## Example Usage
```hcl
// Code block with an example of how to use this resource.
```
## Argument Reference
* `attribute_name` - (Optional/Required) List arguments this resource takes.
## Attribute Reference
* `attribute_name` - List attributes that this resource exports.
### YAML Frontmatter
Markdown source files may contain YAML frontmatter, which provides organizational information and display hints. Frontmatter can be omitted for resources and data sources that don't require a subcategory.
Frontmatter is not rendered in the Terraform Registry web UI.
#### Example
```markdown
---
page_title: "Authenticating with Foo Service via OAuth"
subcategory: "Authentication"
---
```
#### Supported Attributes
The following frontmatter attributes are supported by the Terraform Registry:
* **page_title** - The title of this document, which will display in the docs navigation. This is only required for documents in the `guides/` folder.
* **subcategory** - An optional additional layer of grouping that affects the display of the docs navigation; [see Subcategories below](#subcategories) for more details. Resources and data sources should be organized into subcategories if the number of resources would be difficult to quickly scan for a user. Guides should be separated into subcategories if there are multiple guides which fit into 2 or more distinct groupings.
### Callouts
If you start a paragraph with a special arrow-like sigil, it will become a colored callout box. You can't make multi-paragraph callouts. For colorblind users (and for clarity in general), callouts will automatically start with a strong-emphasized word to indicate their function.
Sigil | Text prefix | Color
------|-------------------|-------
`->` | `**Note**` | blue
`~>` | `**Note**` | yellow
`!>` | `**Warning**` | red
## Navigation Hierarchy
Provider docs are organized by category: resources, data sources, and guides. At a minimum, a provider must contain an index (`docs/index.md`) and at least one resource or data source.
### Typical Structure
A provider named `example` with a resource and data source for `instance` would have these 3 files:
```
docs/
index.md
data-sources/
instance.md
resources/
instance.md
```
After publishing this provider version, its page on the Terraform Registry would display a navigation which resembles this hierarchy:
* example Provider
* Resources
* example_instance
* Data Sources
* example_instance
### Subcategories
To group these resources by a service or other dimension, add the optional `subcategory` field to the YAML frontmatter of the resource and data source:
```markdown
---
subcategory: "Compute"
---
```
This would change the navigation hierarchy to the following:
* example Provider
* Compute
* Resources
* example_instance
* Data Sources
* example_instance
Resources and data sources without a subcategory will be rendered before any subcategories.
The following subcategories will be rendered at the bottom of the list:
* Beta
* Deprecated
### Guides
Providers can optionally include 1 or more guides. These can assist users in using the provider for certain scenarios.
```
docs/
index.md
guides/
authenticating.md
data-sources/
instance.md
resources/
instance.md
```
The title for guides is controlled with the `page_title` attribute in the YAML frontmatter:
```markdown
---
page_title: "Authenticating with Example Cloud"
---
```
The `page_title` is used (instead of the filename) for rendering the link to this guide in the navigation:
* example Provider
* Guides
* Authenticating with Example Cloud
* Resources
* example_instance
* Data Sources
* example_instance
Guides are always rendered before resources, data sources, and any subcategories.
If a `page_title` attribute is not found, the title will default to the filename without the extension.
### Guides Subcategories
If a provider has many guides, you can use subcategories to group them into separate top-level sections. For example, given the following directory structure:
```
docs/
index.md
guides/
authenticating-basic.md
authenticating-oauth.md
setup.md
data-sources/
instance.md
resources/
instance.md
```
Assuming that these three guides have titles similar to their filenames, and the first two include `subcategory: "Authentication"` in their frontmatter, the Terraform Registry would display this navigation structure:
* example Provider
* Guides
* Initial Setup
* Authentication
* Authenticating with Basic Authentication
* Authenticating with OAuth
* Resources
* example_instance
* Data Sources
* example_instance
Guides without a subcategory are always rendered before guides with subcategories. Both are always rendered before resources and data sources.
## Migrating Legacy Providers Docs
For most provider docs already published to [terraform.io][terraform-io-providers], no changes are required to publish them to the Terraform Registry.
~> **Important:** The only exceptions are providers which organize resources, data sources, or guides into subcategories. See the [Subcategories](#subcategories) section above for more information.
If you want to publish docs on the Terraform Registry that are not currently published to terraform.io, take the following steps to migrate to the newer format:
1. Move the `website/docs/` folder to `docs/`
2. Expand the folder names to match the Terraform Registry's expected format:
* Rename `docs/d/` to `docs/data-sources/`
* Rename `docs/r/` to `docs/resources/`
3. Change file suffixes from `.html.markdown` or `.html.md` to `.md`.
[terraform-registry]: https://registry.terraform.io
[terraform-registry-providers]: https://registry.terraform.io/browse/providers
[terraform-io-providers]: https://www.terraform.io/docs/providers/

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.6 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 285 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 6.3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 216 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 17 KiB

View File

@ -1,61 +0,0 @@
---
layout: "registry"
page_title: "Terraform Registry - Providers Overview"
description: |-
Overview of providers in the Terraform Registry
---
# Overview
Providers are how Terraform integrates with any upstream API.
The Terraform Registry is the main source for publicly available Terraform providers. It offers a browsable and searchable interface for finding providers, and makes it possible for Terraform CLI to automatically install any of the providers it hosts.
If you want Terraform to support a new infrastructure service, you can create your own provider using Terraform's Go SDK. Once you've developed a provider, you can use the Registry to share it with the rest of the community.
## Using Providers From the Registry
The Registry is directly integrated with Terraform. To use any provider from the Registry, all you need to do is require it within your Terraform configuration; Terraform can then automatically install that provider when initializing a working directory, and your configuration can take advantage of any resources implemented by that provider.
For more information, see:
- [Configuration Language: Provider Requirements](/docs/configuration/provider-requirements.html)
## Provider Tiers & Namespaces
Terraform providers are published and maintained by a variety of sources, including HashiCorp, HashiCorp Technology Partners, and the Terraform community. The Registry uses tiers and badges to denote the source of a provider. Additionally, namespaces are used to help users identify the organization or publisher responsible for the integration, as shown in the table below.
<table border="0" style="border-collapse: collapse; width: 100%;">
<tbody>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><strong>Tier</strong></td>
<td style="width: 55.7271%; height: 21px;"><strong>Description</strong></td>
<td style="width: 31.7889%; height: 21px;"><strong>Namespace</strong></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="./images/official-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;"><i><span style="font-weight: 400;">Official providers are owned and maintained by HashiCorp </span></i></td>
<td style="width: 31.7889%; height: 21px;"><code><span style="font-weight: 400;">hashicorp</span></code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="./images/verified-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;"><i><span style="font-weight: 400;">Verified providers are owned and maintained by third-party technology partners. Providers in this tier indicate HashiCorp has verified the authenticity of the Provider&rsquo;s publisher, and that the partner is a member of the </span></i><a href="https://www.hashicorp.com/ecosystem/become-a-partner/"><i><span style="font-weight: 400;">HashiCorp Technology Partner Program</span></i></a><i><span style="font-weight: 400;">.</span></i></td>
<td style="width: 31.7889%; height: 21px;"><span style="font-weight: 400;">Third-party organization, e.g. </span><code><span style="font-weight: 400;">mongodb/mongodbatlas</span></code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="./images/community-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;">Community providers are published to the Terraform Registry by individual maintainers, groups of maintainers, or other members of the Terraform community.</td>
<td style="width: 31.7889%; height: 21px;"><br />Maintainer&rsquo;s individual or organization account, e.g. <code>DeviaVir/gsuite</code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="./images/archived-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;">Archived Providers are Official or Verified Providers that are no longer maintained by HashiCorp or the community. This may occur if an API is deprecated or interest was low.</td>
<td style="width: 31.7889%; height: 21px;"><code>hashicorp</code> or third-party</td>
</tr>
</tbody>
</table>
<p></p>
## Verified Provider Development Program
If your organization is interested in joining our Provider Development Program (which sets the standards for publishing providers and modules with a `Verified` badge), please take a look at our [Program Details](/guides/terraform-provider-development-program.html) for further information.

View File

@ -1,28 +0,0 @@
---
layout: "registry"
page_title: "Recommended Provider Binary Operating Systems and Architectures - Terraform Registry"
sidebar_current: "docs-registry-provider-os-arch"
description: |-
Recommended Provider Binary Operating Systems and Architectures
---
# Recommended Provider Binary Operating Systems and Architectures
We recommend the following operating system / architecture combinations for compiled binaries available in the registry (this list is already satisfied by our [recommended **.goreleaser.yml** configuration file](https://github.com/hashicorp/terraform-provider-scaffolding/blob/master/.goreleaser.yml)):
* Darwin / AMD64
* Linux / AMD64 (this is **required** for usage in Terraform Cloud, see below)
* Linux / ARMv8 (sometimes referred to as AArch64 or ARM64)
* Linux / ARMv6
* Windows / AMD64
We also recommend shipping binaries for the following combinations, but we typically do not prioritize fixes for these:
* Linux / 386
* Windows / 386
* FreeBSD / 386
* FreeBSD / AMD64
## Terraform Cloud Compatibility
To ensure your provider can run in Terraform Cloud, please include a Linux / AMD64 binary. This binary should also not have CGO enabled and should not depend on command line execution of any external tools or binaries. We cannot guaruntee availibility of any package/library/binary within the Terraform Cloud images.

View File

@ -1,129 +0,0 @@
---
layout: "registry"
page_title: "Terraform Registry - Publishing Providers"
sidebar_current: "docs-registry-provider-publishing"
description: |-
Publishing Providers to the Terraform Registry
---
# Publishing Providers
Anyone can publish and share a provider by signing into the Registry using their GitHub account and following a few additional steps.
This page describes how to prepare a [Terraform Provider](/docs/plugins/provider.html) for publishing, and how to publish a prepared provider using the Registry's interface.
## Preparing your Provider
### Writing a Provider
Providers published to the Terraform Registry are written and built in the same way as other Terraform providers. A variety of resources are available to help our contributors build a quality integration:
- The [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn
- [How to build a provider Video](https://www.youtube.com/watch?v=2BvpqmFpchI)
- [Sample provider developed by a HashiCorp partner](https://blog.container-solutions.com/write-terraform-provider-part-1)
- Example providers for reference:
- [AWS](https://github.com/terraform-providers/terraform-provider-aws)
- [AzureRM](https://github.com/terraform-providers/terraform-provider-azurerm)
- [Contributing to Terraform guidelines](/docs/extend/community/contributing.html)
~> **Important:** In order to be detected by the Terraform Registry, all provider repositories on GitHub must match the pattern `terraform-provider-{NAME}`, and the repository must be public.
### Documenting your Provider
Your provider should contain an overview document (index.md), as well as a doc for each resource and data-source. See [Documenting Providers](./docs.html) for details about how to ensure your provider documentation renders properly on the Terraform Registry.
-> **Note:** In order to test how documents will render in the Terraform Registry, you can use the [Terraform Registry Doc Preview Tool](https://registry.terraform.io/tools/doc-preview).
### Creating a GitHub Release
Publishing a provider requires at least one version be available on GitHub Releases. The tag must be a valid [Semantic Version](https://semver.org/) preceded with a `v` (for example, `v1.2.3`).
Terraform CLI and the Terraform Registry follow the Semantic Versioning specification when detecting a valid version, sorting versions, solving version constraints, and choosing the latest version. Prerelease versions are supported (available if explicitly defined but not chosen automatically) with a hyphen (-) delimiter, such as `v1.2.3-pre`.
We have a list of [recommend OS / architecture combinations](/docs/registry/providers/os-arch.html) for which we suggest most providers create binaries.
~> **Important:** Avoid modifying or replacing an already-released version of a provider, as this will cause checksum errors for users when attempting to download the plugin. Instead, if changes are necessary, please release as a new version.
#### GitHub Actions (Preferred)
[GitHub Actions](https://docs.github.com/en/actions) allow you to execute workflows when events on your repository occur. You can use this to publish provider releases to the Terraform Registry whenever a new version tag is created on your repository.
To use GitHub Actions to publish new provider releases to the Terraform Registry:
1. Create and export a signing key that you plan on using to sign your provider releases. See [Preparing and Adding a Signing Key](#preparing-and-adding-a-signing-key) for more information.
1. Copy the [GoReleaser configuration from the terraform-provider-scaffolding repository](https://github.com/hashicorp/terraform-provider-scaffolding/blob/master/.goreleaser.yml) to the root of your repository.
1. Copy the [GitHub Actions workflow from the terraform-provider-scaffolding repository](https://github.com/hashicorp/terraform-provider-scaffolding/blob/master/.github/workflows/release.yml) to `.github/workflows/release.yml` in your repository.
1. Go to *Settings > Secrets* in your repository, and add the following secrets:
* `GPG_PRIVATE_KEY` - Your ASCII-armored GPG private key. You can export this with `gpg --armor --export-secret-keys [key ID or email]`.
* `PASSPHRASE` - The passphrase for your GPG private key.
1. Push a new valid version tag (e.g. `v1.2.3`) to test that the GitHub Actions releaser is working.
Once a release is created, you can move on to [Publishing to the Registry](#publishing-to-the-registry).
#### Using GoReleaser locally
GoReleaser is a tool for building Go projects for multiple platforms, creating a checksums file, and signing the release. It can also upload your release to GitHub Releases.
1. Install [GoReleaser](https://goreleaser.com) using the [installation instructions](https://goreleaser.com/install/).
1. Copy the [.goreleaser.yml file](https://github.com/hashicorp/terraform-provider-scaffolding/blob/master/.goreleaser.yml) from the [hashicorp/terraform-provider-scaffolding](https://github.com/hashicorp/terraform-provider-scaffolding) repository.
1. Cache the password for your GPG private key with `gpg --armor --detach-sign` (see note below).
1. Set your `GITHUB_TOKEN` to a [Personal Access Token](https://github.com/settings/tokens/new?scopes=public_repo) that has the **public_repo** scope.
1. Tag your version with `git tag v1.2.3`.
1. Build, sign, and upload your release with `goreleaser release --rm-dist`.
-> GoReleaser does not support signing binaries with a GPG key that requires a passphrase. Some systems may cache your GPG passphrase for a few minutes. If you are unable to cache the passphrase for GoReleaser, please use the manual release preparation process below, or remove the signature step from GoReleaser and sign it prior to moving the GitHub release from draft to published.
#### Manually Preparing a Release
If for some reason you're not able to use GoReleaser to build, sign, and upload your release, you can create the required assets by following these steps, or encode them into a Makefile or shell script.
The release must meet the following criteria:
* There are 1 or more zip files containing the built provider binary for a single architecture
* The binary name is `terraform-provider-{NAME}_v{VERSION}`
* The archive name is `terraform-provider-{NAME}_{VERSION}_{OS}_{ARCH}.zip`
* There is a `terraform-provider-{NAME}_{VERSION}_SHA256SUMS` file, which contains a sha256 sum for each zip file in the release.
* `shasum -a 256 *.zip > terraform-provider-{NAME}_{VERSION}_SHA256SUMS`
* There is a `terraform-provider-{NAME}_{VERSION}_SHA256SUMS.sig` file, which is a valid GPG signature of the `terraform-provider-{NAME}_{VERSION}_SHA256SUMS` file using the keypair.
* `gpg --detach-sign terraform-provider-{NAME}_{VERSION}_SHA256SUMS`
* Release is finalized (not a private draft).
## Publishing to the Registry
### Signing in
Before publishing a provider, you must first sign in to the Terraform Registry with a GitHub account (see [Signing into the Registry](/docs/registry/index.html#creating-an-account)). The GitHub account used must have the following permission scopes on the provider repository youd like to publish. Permissions can be verified by going to your [GitHub Settings](https://github.com/settings/connections/applications/) and selecting the Terraform Registry Application under Authorized OAuth Apps.
![screenshot: terraform registry github oauth required permissions](./images/github-oauth-permissions.png)
### Preparing and Adding a Signing Key
All provider releases are required to be signed, thus you must provide HashiCorp with the public key for the GPG keypair that you will be signing releases with. The Terraform Registry will validate that the release is signed with this key when publishing each version, and Terraform will verify this during `terraform init`.
- Generate a GPG key to be used when signing releases (See [GitHub's detailed instructions](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key) for help with this step, but you do not need to add the key to GitHub)
- Export your public key in ASCII-armor format using the following command, substituting the GPG key ID created in the step above:
```console
$ gpg --armor --export "{Key ID or email address}"
```
The ASCII-armored public key to the Terraform Registry by going to [User Settings > Signing Keys](https://registry.terraform.io/settings/gpg-keys). You can add keys for your personal namespace, or any organization which you are an admin of.
### Publishing Your Provider
In the top-right navigation, select [Publish > Provider](https://registry.terraform.io/publish/provider) to begin the publishing process. Follow the prompts to select the organization and repository you would like to publish.
#### Webhooks
Publishing a provider will create a webhook on the GitHub repository subscribed to `release` events. Future versions released will notify the Terraform Registry, which will then ingress that version.
If the webhook is missing or not functioning, you can use the Resync button on the provider settings page. First, remove any existing webhooks for registry.terraform.io. Then, click the Resync button on the Terraform Registry's provider settings page. A new webhook should be created.
#### Terms of Use
Anything published to the Terraform Registry is subject to our terms of use. A copy of the terms are available for viewing at https://registry.terraform.io/terms
### Support
If you experience issues publishing your provider to the Terraform Registry, please contact us at [terraform-registry@hashicorp.com](mailto:terraform-registry@hashicorp.com).

View File

@ -1,70 +0,0 @@
<% wrap_layout :inner do %>
<% content_for :sidebar do %>
<h4><a href="/docs/registry/index.html">Publishing Providers &amp; Modules</a></h4>
<ul class="nav docs-sidenav">
<li>
<a href="/docs/registry/index.html">Overview</a>
</li>
<li>
<a href="#">Providers</a>
<ul class="nav nav-auto-expand">
<li>
<a href="/docs/registry/providers/index.html">Overview</a>
</li>
<li>
<a href="/docs/registry/providers/publishing.html">Publishing Providers</a>
</li>
<li>
<a href="/docs/plugins/signing.html">Plugin Signing</a>
</li>
<li>
<a href="/docs/registry/providers/docs.html">Documenting Providers</a>
</li>
<li>
<a href="/docs/registry/providers/os-arch.html">Recommended OS and Architecture</a>
</li>
<li>
<a href="/guides/terraform-provider-development-program.html">Provider Development Program</a>
</li>
</ul>
</li>
<li>
<a href="#">Modules</a>
<ul class="nav nav-auto-expand">
<li>
<a href="/docs/registry/modules/use.html">Finding and Using Modules</a>
</li>
<li>
<a href="/docs/registry/modules/publish.html">Publishing Modules</a>
</li>
<li>
<a href="/docs/registry/modules/verified.html">Verified Modules</a>
</li>
</ul>
</li>
<li>
<a href="/docs/registry/private.html">Private Registries</a>
</li>
<li>
<a href="/docs/registry/api.html">Registry API</a>
</li>
</ul>
<%= partial("layouts/otherdocs", :locals => { :skip => "Publishing Providers and Modules" }) %>
<% end %>
<%= yield %>
<% end %>