ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

website: Revise the "Modules" configuration docs section 

This adopts a more guide-like writing style, similar to what prior commits
have done to some other subsections of this section.

Since we already have a whole top-level section devoted to modules, there
is no need for full coverage of all of their features here. Instead, this
section focuses on an an initial introduction to what modules are and
the basics of their usage within the Terraform language. We then link
to the main modules section for the full details.
This commit is contained in:
Martin Atkins 2018-05-05 20:38:38 -07:00
parent fdc8bb6c00
commit eeb96b1e12
2 changed files with 88 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
website/docs/configuration/modules.html.md
View File

@ -3,46 +3,84 @@ layout: "docs"
page_title: "Configuring Modules" page_title: "Configuring Modules"
sidebar_current: "docs-config-modules" sidebar_current: "docs-config-modules"
description: |- description: |-
Modules are used in Terraform to modularize and encapsulate groups of resources in your infrastructure. For more information on modules, see the dedicated modules section. Modules allow multiple resources to be grouped together and encapsulated.
--- ---
# Module Configuration # Modules
Modules are used in Terraform to modularize and encapsulate groups of A _module_ is a container for multiple resources that are used together.
resources in your infrastructure. For more information on modules, see Every Terraform configuration has at least one module, known as its
the dedicated _root module_, which consists of the resources defined in the `.tf` files in
[modules section](/docs/modules/index.html). the main working directory.
This page assumes you're familiar with the A module can call other modules, allowing the suite of resources within the
[configuration syntax](/docs/configuration/syntax.html) child module to be included into the configuration in a concise way. Modules
already. can also be called multiple times, either within the same configuration or
in separate configurations, allowing resource configurations to be packaged
and re-used.
## Example This page describes how to call one module from another. Other pages in this
section of the documentation describe the different elements that make up
modules, and there is further information about how modules can be used,
created, and published in [the dedicated _Modules_ section](/docs/modules/index.html).
## Calling a Child Module
To _call_ a module means to include the contents of that module into the
configuration with specific values for its
[input variables](/docs/configuration/variables.html). Modules are called
from within other modules using `module` blocks:
```hcl ```hcl
module "consul" { module "servers" {
source = "hashicorp/consul/aws" source = "./app-cluster"
servers = 5 servers = 5
} }
``` ```
## Description The label immediately after the `module` keyword is a name that will be used
to refer to this instance of the module within the calling module. The
_calling module_ is the one that includes the `module` block shown above.
A `module` block instructs Terraform to create an instance of a module, Within the block body (between `{` and `}`) are the arguments for the module.
and in turn to instantiate any resources defined within it. Most of the arguments correspond to [input variables](/docs/configuration/variables.html)
defined by the module, including the `servers` argument in the above example.
The name given in the block header is used to reference the particular module The `source` argument is a meta-argument defined and processed by Terraform
instance from expressions within the calling module, and to refer to the itself. Its value is the path to a local directory containing the module's
module on the command line. It has no meaning outside of a particular configuration files, or optionally a remote module source that Terraform should
Terraform configuration. download and use. For more information on possible values for this argument,
see [_Module Sources_](/docs/modules/sources.html).
Within the block body is the configuration for the module. All attributes The same source address can be specified in multiple `module` blocks to create
within the block must correspond to [variables](/docs/configuration/variables.html) multiple copies of the resources defined within, possibly with different
within the module, with the exception of the following which Terraform variable values.
treats as special:
* `source` - (Required) A [module source](/docs/modules/sources.html) string ## Accessing Module Output Values
specifying the location of the child module source code.
The resources defined in a module are encapsulated, so the calling module
cannot access their attributes directly. However, the child module can
declare [output values](/docs/configuration/outputs.html) to selectively
export certain values to be accessed by the calling module.
For example, if the `./app-cluster` module referenced in the example above
exported an output value named `instance_ids` then the calling module
can reference that result using the expression `module.servers.instance_ids`:
```hcl
resource "aws_elb" "example" {
# ...
instances = module.servers.instance_ids
}
```
## Other Meta-arguments
Along with the `source` meta-argument described above, module blocks have
some more meta-arguments that have special meaning across all modules,
described in more detail in other sections:
* `version` - (Optional) A [version constraint](/docs/modules/usage.html#module-versions) * `version` - (Optional) A [version constraint](/docs/modules/usage.html#module-versions)
string that specifies which versions of the referenced module are acceptable. string that specifies which versions of the referenced module are acceptable.
@ -55,3 +93,11 @@ treats as special:
[provider configurations to be passed explicitly to child modules](/docs/modules/usage.html#providers-within-modules). [provider configurations to be passed explicitly to child modules](/docs/modules/usage.html#providers-within-modules).
If not specified, the child module inherits all of the default (un-aliased) If not specified, the child module inherits all of the default (un-aliased)
provider configurations from the calling module. provider configurations from the calling module.
In addition to the above, the argument names `count`, `for_each` and
`lifecycle` are not currently used by Terraform but are reserved for planned
future features.
Since modules are a complex feature in their own right, further detail
about how modules can be used, created, and published is included in
[the dedicated section on modules](/docs/modules/index.html).

17
website/docs/configuration/variables.html.md
View File

@ -60,6 +60,23 @@ if no overridden value is set when calling the module. The `default` argument
requires a literal value and cannot reference other objects in the requires a literal value and cannot reference other objects in the
configuration. configuration.
## Using Input Variable Values
Within the module that declared a variable, its value can be accessed from
within [expressions](/docs/configuration/expressions.html) using an expression
like `var.image_id`, where the name after the period corresponds to the label
given in the declaration block:
```hcl
resource "aws_instance" "example" {
instance_type = "t2.micro"
ami = var.image_id
}
```
The value assigned to a variable can be accessed only from expressions within
the module where it was declared.
## Type Constraints ## Type Constraints
The `type` argument in a `variable` block allows you to restrict the type of The `type` argument in a `variable` block allows you to restrict the type of