website: working on registry docs

This commit is contained in:
Mitchell Hashimoto 2017-08-14 23:35:33 -07:00 committed by Paul Banks
parent 1c098ce4ec
commit bf7f4d243d
6 changed files with 127 additions and 8 deletions

View File

@ -14,6 +14,11 @@ the Terraform files you're applying comprise what is called the _root module_. T
Therefore, you can enter the source of any module, satisfy any required variables, run `terraform apply`, and expect it to work.
Modules that are created for reuse should follow the
[standard structure](#standard-structure). This structure enables tooling
such as the [Terraform Registry](/docs/registry/index.html) to inspect and
generate documentation, read examples, and more.
## An Example Module
Within a folder containing Terraform configurations, create a subfolder called `child`. In this subfolder, make one empty `main.tf` file. Then, back in the root folder containing the `child` folder, add this to one of your Terraform configuration files:
@ -89,3 +94,7 @@ variables and outputs you require.
The [get command](/docs/commands/get.html) will automatically get all nested modules.
You don't have to worry about conflicting versions of modules, since Terraform builds isolated subtrees of all dependencies. For example, one module might use version 1.0 of module `foo` and another module might use version 2.0, and this will all work fine within Terraform since the modules are created separately.
## Standard Structure
TODO

View File

@ -7,14 +7,17 @@ description: Explains the use of the source parameter, which tells Terraform whe
# Module Sources
As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`. The `source` parameter tells Terraform where the module can be found and what constraints to put on the module. Constraints can include a specific version or Git branch.
As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`.
The `source` parameter tells Terraform where the module can be found.
Terraform manages modules for you: it downloads them, organizes them on disk, checks for updates, etc. Terraform uses this `source` parameter to determine where it should retrieve and update modules from.
Terraform supports the following sources:
* Local file paths
* [Terraform Registry](/docs/registry/index.html)
* GitHub
* Bitbucket
@ -39,6 +42,27 @@ module "consul" {
Updates for file paths are automatic: when "downloading" the module using the [get command](/docs/commands/get.html), Terraform will create a symbolic link to the original directory. Therefore, any changes are automatically available.
## Terraform Registry
The [Terraform Registry](https://registry.terraform.io) is an index of modules
written by the Terraform community.
The Terraform Registry is the easiest
way to get started with Terraform and to find modules to start with.
The registry is integrated directly into Terraform:
```hcl
module "consul" {
source = "hashicorp/consul/aws"
}
```
The above example would use the
[Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
from the public registry.
You can learn more about the registry at the
[Terraform Registry documentation section](/docs/registry/index.html).
## GitHub
Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple:

View File

@ -11,16 +11,21 @@ Using modules in Terraform is very similar to defining resources:
```shell
module "consul" {
source = "github.com/hashicorp/consul/terraform/aws"
source = "hashicorp/consul/aws"
servers = 3
}
```
You can view the full documentation for configuring modules in the [Module Configuration](/docs/configuration/modules.html) section.
In modules we only specify a name rather than a name and a type (as in resources). This name can be used elsewhere in the configuration to reference the module and its variables.
In modules we only specify a name rather than a name and a type (as in resources). This name can be used elsewhere in the configuration to reference the module and its outputs.
The existence of the above configuration will tell Terraform to create the resources in the `consul` module which can be found on GitHub at the given URL. Just like a resource, the module configuration can be deleted to remove the module.
The source tells Terraform what to create. In this example, we create
the [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
from the [Terraform Registry](https://registry.terraform.io). You can learn
more about the [source configuration below](#source).
Just like a resource, the module configuration can be deleted to remove the module.
## Multiple instances of a module
@ -62,8 +67,14 @@ The resource names in your module get prefixed by `module.<module-instance-name
## Source
The only required configuration key for a module is the `source` parameter. The value of this tells Terraform where the module can be downloaded, updated, etc. Terraform comes with support for a variety of module sources. These
are documented in the [Module sources documentation](/docs/modules/sources.html).
The only required configuration key for a module is the `source` parameter. The value of this tells Terraform where the module can be downloaded, updated, etc. Terraform comes with support for a variety of module sources. The recommended source for modules is a
[Terraform Registry](/docs/registry/index.html) since this enables additional
features for modules such as versioning.
Terraform can also download modules directly from various storage providers
and version control systems. These sources do not support versioning and other
registry benefits. The full list of available sources
are documented in the [module sources documentation](/docs/modules/sources.html).
Prior to running any Terraform command with a configuration that uses modules, you'll have to [get](/docs/commands/get.html) the modules. This is done using the [get command](/docs/commands/get.html).

View File

@ -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.

View File

@ -510,8 +510,8 @@
<a href="/docs/modules/sources.html">Sources</a>
</li>
<li<%= sidebar_current("docs-modules-registry") %>>
<a href="/docs/modules/registry.html">Registry</a>
<li<%= sidebar_current("docs-registry") %>>
<a href="/docs/registry/index.html">Registry</a>
</li>
<li<%= sidebar_current("docs-modules-create") %>>

View File

@ -0,0 +1,40 @@
<% 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-use") %>>
<a href="/docs/registry/modules/use.html">Publishing Modules</a>
</li>
</ul>
</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 %>