website: working on registry docs
This commit is contained in:
parent
1c098ce4ec
commit
bf7f4d243d
|
@ -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
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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).
|
||||
|
||||
|
|
|
@ -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.
|
|
@ -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") %>>
|
||||
|
|
|
@ -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 %>
|
Loading…
Reference in New Issue