diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index 860c56564..a3a25d4a7 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -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 diff --git a/website/docs/modules/sources.html.markdown b/website/docs/modules/sources.html.markdown index e5b1a971a..441bdc29f 100644 --- a/website/docs/modules/sources.html.markdown +++ b/website/docs/modules/sources.html.markdown @@ -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: diff --git a/website/docs/modules/usage.html.markdown b/website/docs/modules/usage.html.markdown index 79782a746..3ba349e57 100644 --- a/website/docs/modules/usage.html.markdown +++ b/website/docs/modules/usage.html.markdown @@ -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.Sources - > - Registry + > + Registry > diff --git a/website/layouts/registry.erb b/website/layouts/registry.erb new file mode 100644 index 000000000..83abe4bc5 --- /dev/null +++ b/website/layouts/registry.erb @@ -0,0 +1,40 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %>