Merge pull request #26968 from hashicorp/nov20_remove_registry
website: Remove registry docs (adopted into terraform-website)
This commit is contained in:
Nick Fagerlund
GitHub
commit
f488a75998
|
|
@ -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 |
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
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 you’re looking for. (Note that search supports keyboard navigation.)
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 97 KiB |
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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 modules are expected to be actively maintained by HashiCorp partners.
|
||||
The verified badge isn’t 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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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 |
|
|
@ -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’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’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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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 you’d 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.
|
||||
|
||||
|
||||
|
||||
### 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).
|
||||
|
|
@ -1,70 +0,0 @@
|
|||
<% wrap_layout :inner do %>
|
||||
<% content_for :sidebar do %>
|
||||
<h4><a href="/docs/registry/index.html">Publishing Providers & 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 %>
|
||||
Loading…
Reference in New Issue