mirror of https://github.com/hashicorp/terraform
James Bardin
9 years ago
commit
50005ec817
@ -0,0 +1,490 @@
|
||||
---
|
||||
layout: "registry"
|
||||
page_title: "Terraform Registry - HTTP API"
|
||||
sidebar_current: "docs-registry-api"
|
||||
description: |-
|
||||
The /acl endpoints create, update, destroy, and query ACL tokens in Consul.
|
||||
---
|
||||
|
||||
# HTTP API
|
||||
|
||||
The [Terraform Registry](https://registry.terraform.io) has an HTTP API for
|
||||
reading and downloading registry modules.
|
||||
|
||||
Terraform interacts with the registry as read-only. Therefore, the documented
|
||||
API is read-only. Any endpoints that aren't documented on this page can and will
|
||||
likely change over time. This allows differing methods for getting modules into
|
||||
the registry while keeping a consistent API for reading modules in the registry.
|
||||
|
||||
## List Latest Version of Module for All Providers
|
||||
|
||||
This endpoint returns the latest version of each provider for a module.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/v1/modules/: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 Module for a Single Provider
|
||||
|
||||
This endpoint returns the latest version of a module for a single provider.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/v1/modules/: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` | `/v1/modules/: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 a Specific Module
|
||||
|
||||
This endpoint downloads the specified version of a module for a single provider.
|
||||
|
||||
A successful response has no body, and includes the URL from which the module
|
||||
version's source can be downloaded in the `X-Terraform-Get` header. Note that
|
||||
this URL 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.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/v1/modules/: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
|
||||
```
|
||||
|
||||
## 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` | `/v1/modules/: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.
|
||||
|
||||
- `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/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 sane default limit and a
|
||||
default offset of `0`. Each endpoint will also apply a sane 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`.
|
||||
@ -0,0 +1,35 @@
|
||||
---
|
||||
layout: "registry"
|
||||
page_title: "Terraform Registry"
|
||||
sidebar_current: "docs-registry-home"
|
||||
description: |-
|
||||
The Terraform Registry is a repository of modules written by the Terraform community.
|
||||
---
|
||||
|
||||
# Terraform Registry
|
||||
|
||||
The [Terraform Registry](https://registry.terraform.io) is a repository
|
||||
of modules written by the Terraform community. The registry can be used to
|
||||
help you get started with Terraform more quickly, see examples of how
|
||||
Terraform is written, and find pre-made modules for infrastructure components
|
||||
you require.
|
||||
|
||||
The Terraform Registry is integrated directly into Terraform to make
|
||||
consuming modules easy. The following example shows how easy it is to
|
||||
build a fully functional [Consul](https://www.consul.io) cluster using the
|
||||
[Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws).
|
||||
|
||||
```hcl
|
||||
module "consul" {
|
||||
source = "hashicorp/consul/aws"
|
||||
}
|
||||
```
|
||||
|
||||
You can also publish your own modules on the Terraform Registry. You may
|
||||
use the [public registry](https://registry.terraform.io) for public modules.
|
||||
For private modules, you must use [Terraform Enterprise](https://www.hashicorp.com/products/terraform).
|
||||
You can use modules without a registry by
|
||||
[sourcing modules directly](/docs/modules/sources.html), however non-registry
|
||||
modules do not support versioning, documentation generation, and more.
|
||||
|
||||
Use the navigation to the left to learn more about using the registry.
|
||||
@ -0,0 +1,92 @@
|
||||
---
|
||||
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 the name of the module, the provider, the documentation,
|
||||
inputs/outputs, and more directly from the source of the module. No manual
|
||||
annotations are required.
|
||||
|
||||
## Requirements
|
||||
|
||||
The list below contains all the requirements for publishing a module.
|
||||
Meeting the requirements for publishing a module is extremely easy. The
|
||||
list may appear long only to ensure we're detailed, but adhering to the
|
||||
requirements should happen naturally.
|
||||
|
||||
* **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.
|
||||
|
||||
* **Repository name.** The repository name must be `terraform-PROVIDER-NAME`
|
||||
where PROVIDER is the primary provider to associate with the module and
|
||||
NAME is a unique name for the module. The name may contain hyphens. Example:
|
||||
`terraform-aws-consul` or `terraform-google-vault`.
|
||||
|
||||
* **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/create.html#standard-module-structure).
|
||||
This allows the registry to inspect your module and generate documentation,
|
||||
track resource usage, and more.
|
||||
|
||||
* **Tags for Releases.** Releases are detected by creating and pushing
|
||||
tags. The tag name must be a semantic version that can optionally be prefixed
|
||||
with a `v`. Examples are `v1.0.4` and `0.9.2`. To publish a module initially,
|
||||
at least one release tag must be present.
|
||||
|
||||
## 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 "Force GitHub Sync"
|
||||
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.
|
||||
@ -0,0 +1,54 @@
|
||||
---
|
||||
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 may view unverified
|
||||
modules as well.
|
||||
|
||||
## Using Modules
|
||||
|
||||
The Terraform Registry is integrated directly into Terraform. This makes
|
||||
it easy to reference any module in the registry. The syntax for referencing
|
||||
a registry module is `namespace/name/provider`. For example:
|
||||
`hashicorp/consul/aws`.
|
||||
|
||||
When viewing a module on the registry on a tablet or desktop, usage instructions
|
||||
are shown on the right side. The screenshot below shows where to find these.
|
||||
You can copy and paste this to get started with any module. Some modules may
|
||||
have required inputs you must set before being able to use the module.
|
||||
|
||||
```hcl
|
||||
module "consul" {
|
||||
source = "hashicorp/consul/aws"
|
||||
}
|
||||
```
|
||||
|
||||
## 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 encourge all modules to follow the full guidelines of semantic versioning.
|
||||
|
||||
Terraform currently only downloads the latest version of each module. The
|
||||
next release of Terraform (0.11) will bring full support for constraining
|
||||
module versions. The registry has the required semantic versions since launch
|
||||
to prepare for this transition shortly after.
|
||||
@ -0,0 +1,32 @@
|
||||
---
|
||||
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 blue verification badge appears next to modules that are verified.
|
||||
|
||||
|
||||
|
||||
If a module is verified, it is promised to be actively maintained and of
|
||||
high quality. It 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.
|
||||
|
||||
Module verification is currently a manual process restricted to a small group
|
||||
of trusted HashiCorp partners. In the coming months, we'll be expanding
|
||||
verification to enable the broader community to verify their modules.
|
||||
|
||||
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.
|
||||
@ -0,0 +1,37 @@
|
||||
---
|
||||
layout: "registry"
|
||||
page_title: "Terraform Registry - Private Registry"
|
||||
sidebar_current: "docs-registry-private"
|
||||
description: |-
|
||||
Terraform is capable of loading modules from private registries for private modules via Terraform Enterprise.
|
||||
---
|
||||
|
||||
# Private Registry
|
||||
|
||||
The registry at [registry.terraform.io](https://registry.terraform.io)
|
||||
may only host public modules. Terraform is capable of loading modules from
|
||||
private registries for private modules.
|
||||
|
||||
Official private registries are available via [Terraform Enterprise](#).
|
||||
There are two tiers: Pro and Enterprise. The Pro version is only available
|
||||
as a SaaS service whereas the Enterprise version is available for private
|
||||
install. Both versions fully support private registries.
|
||||
|
||||
The Terraform project does not provide any free or open source solution to have
|
||||
a private registry. Terraform only requires the [read API](/docs/registry/api.html)
|
||||
to be available to load modules from a registry.
|
||||
Support for specifying an alternative to the public registry will be available
|
||||
in Terraform 0.11. We welcome the community to create their own private
|
||||
registries by recreating this API.
|
||||
|
||||
## Coming Soon
|
||||
|
||||
Terraform Enterprise is currently in beta and does not allow open signups.
|
||||
|
||||
Terraform Enterprise will be publicly available for self service signup
|
||||
by the end of 2017. In the mean time, if you're interested in private
|
||||
registries and being part of the beta, please contact us at
|
||||
[hello@hashicorp.com](mailto:hello@hashicorp.com).
|
||||
|
||||
When Terraform Enterprise is publicly available, the documentation will
|
||||
be available here.
|
||||
@ -0,0 +1,16 @@
|
||||
---
|
||||
layout: "registry"
|
||||
page_title: "Terraform Registry - Support"
|
||||
sidebar_current: "docs-registry-support"
|
||||
description: |-
|
||||
Where to go for help with modules found in the Terraform Registry.
|
||||
---
|
||||
|
||||
# Getting Help
|
||||
|
||||
The modules in The Terraform Registry are provided and maintained by trusted
|
||||
HashiCorp partners and the Terraform Community. If you run into issues using a
|
||||
module or have additional contributions to make, you can find a link to the
|
||||
Module's GitHub issues on the module page.
|
||||
|
||||
|
||||
@ -0,0 +1,48 @@
|
||||
<% wrap_layout :inner do %>
|
||||
<% content_for :sidebar do %>
|
||||
<ul class="nav docs-sidenav">
|
||||
<li<%= sidebar_current("docs-home") %>>
|
||||
<a class="back" href="/docs/index.html">Documentation Home</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-home") %>>
|
||||
<a class="back" href="/docs/registry/index.html">Terraform Registry</a>
|
||||
</li>
|
||||
|
||||
<hr>
|
||||
|
||||
<li class="active">
|
||||
<a href="#">Modules</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-registry-use") %>>
|
||||
<a href="/docs/registry/modules/use.html">Finding and Using Modules</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-publish") %>>
|
||||
<a href="/docs/registry/modules/publish.html">Publishing Modules</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-verified") %>>
|
||||
<a href="/docs/registry/modules/verified.html">Verified Modules</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-private") %>>
|
||||
<a href="/docs/registry/private.html">Private Registry</a>
|
||||
</li>
|
||||
|
||||
<hr>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-api") %>>
|
||||
<a href="/docs/registry/api.html">API</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-support") %>>
|
||||
<a href="/docs/registry/support.html">Support</a>
|
||||
</li>
|
||||
</ul>
|
||||
<% end %>
|
||||
|
||||
<%= yield %>
|
||||
<% end %>
|
||||
Loading…
Reference in new issue