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

Rewrite of the module usage page 

Tidied up the page and fixed some formatting, style and naming issues.
This commit is contained in:
James Turnbull 2016-10-01 09:48:58 -04:00 committed by GitHub
parent 59b67efd8a
commit 862ef46a49
1 changed files with 23 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
website/source/docs/modules/usage.html.markdown
View File

@ -16,17 +16,11 @@ module "consul" {
} }
``` ```
You can view the full documentation for the syntax of configuring You can view the full documentation for configuring modules in the [Module Configuration](/docs/configuration/modules.html) section.
modules [here](/docs/configuration/modules.html).
As you can see, it is very similar to defining resources, with the exception As you can see, configuring modules is very similar to defining resources, with the exception that we only specify a name rather than a name and a type. This name can be used elsewhere in the configuration to reference the module and its variables.
that we don't specify a type, and just a name. This name can be used elsewhere
in the configuration to reference the module and its variables.
The existence of the above configuration will tell Terraform to create 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 resources in the "consul" module which can be found on GitHub with the
given URL. Just like a resource, the module configuration can be deleted
to remove the module.
## Multiple instances of a module ## Multiple instances of a module
@ -58,33 +52,18 @@ resource "aws_iam_user" "deploy_user" {
} }
``` ```
In this example you can provide module implementation in the `./publish_bucket` In this example you define a module in the `./publish_bucket` subdirectory. That module has configuration to create a bucket resource, set access and caching rules. The module wraps the bucket and all the other implementation details required to configure a bucket.
subfolder - define there, how to create a bucket resource, set access and
caching rules, create e.g. a CloudFront resource, which wraps the bucket and
all the other implementation details, which are common to your project.
In the snippet above, you now use your module definition twice. The string We can then define the module multiple times in our configuration by naming each instantiation of the module uniquely, here `module "assets_bucket"` and `module "media_bucket"`, whilst specifying the same module `source`.
after the `module` keyword is a name of the instance of the module.
Note: the resource names in your implementation get prefixed by the The resource names in your module get prefixed by `module.<module-instance-name>` when instantiated, for example the `publish_bucket` module creates `aws_s3_bucket.the_bucket` and `aws_iam_access_key.deploy_user`. The full name of the resulting resources will be `module.assets_bucket.aws_s3_bucket.the_bucket` and `module.assets_bucket.aws_iam_access_key.deploy_user`. Be cautious of this when extracting configuration from your files into a module, the name of your resources will change and Terraform will potentially destroy and recreate them. Always check your configuration with `terraform plan` before running `terraform apply`.
`module.<module-instance-name>` when instantiated. Example: your `publish_bucket`
implementation creates `aws_s3_bucket.the_bucket` and `aws_iam_access_key.deploy_user`.
The full name of the resulting resources will be `module.assets_bucket.aws_s3_bucket.the_bucket`
and `module.assets_bucket.aws_iam_access_key.deploy_user`. So beware, if you
extract your implementation to a module. The resource names will change and
this will lead to destroying s3 buckets and creating new ones - so always
check with `tf plan` before running `tf apply`.
## Source ## Source
The only required configuration key is the `source` parameter. The value of 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
this tells Terraform where the module can be downloaded, updated, etc. are documented in the [Module sources documentation](/docs/modules/sources.html).
Terraform comes with support for a variety of module sources. These
are documented on a [separate page](/docs/modules/sources.html).
Prior to running any command such as `plan` with a configuration that 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).
uses modules, you'll have to [get](/docs/commands/get.html) the modules.
This is done using the [get command](/docs/commands/get.html).
``` ```
$ terraform get $ terraform get
@ -92,25 +71,19 @@ $ terraform get
``` ```
This command will download the modules if they haven't been already. This command will download the modules if they haven't been already.
By default, the command will not check for updates, so it is safe (and fast)
to run multiple times. You can use the `-update` flag to check and download By default, the command will not check for updates, so it is safe (and fast) to run multiple times. You can use the `-update` flag to check and download updates.
updates.
## Configuration ## Configuration
The parameters used to configure modules, such as the `servers` parameter The parameters used to configure modules, such as the `servers` parameter above, map directly to [variables](/docs/configuration/variables.html) within the module itself. Therefore, you can quickly discover all the configuration
above, map directly to [variables](/docs/configuration/variables.html) within for a module by inspecting the source of it.
the module itself. Therefore, you can quickly discover all the configuration
for a module by inspecting the source of it very easily.
Additionally, because these map directly to variables, module configuration can Additionally, because these map directly to variables, module configuration can have any data type available for variables, including maps and lists.
have any data type supported by variables, including maps and lists.
## Outputs ## Outputs
Modules can also specify their own [outputs](/docs/configuration/outputs.html). Modules can also specify their own [outputs](/docs/configuration/outputs.html). These outputs can be referenced in other places in your configuration, for example:
These outputs can be referenced in other places in your configuration.
For example:
``` ```
resource "aws_instance" "client" { resource "aws_instance" "client" {
@ -120,44 +93,34 @@ resource "aws_instance" "client" {
} }
``` ```
This purposely is very similar to accessing resource attributes. But instead This purposely is very similar to accessing resource attributes. Instead of mapping to a resource, however, the variable in this case maps to an output of a module.
of mapping to a resource, the variable in this case maps to an output of
a module.
Just like resources, this will create a dependency from the `aws_instance.client` Just like resources, this will create a dependency from the `aws_instance.client` resource to the module, so the module will be built first.
resource to the module, so the module will be built first.
## Plans and Graphs ## Plans and Graphs
With modules, commands such as the [plan command](/docs/commands/plan.html) Commands such as the [plan command](/docs/commands/plan.html) and [graph command](/docs/commands/graph.html) will expand modules by default. You can use the `-module-depth` parameter to limit the graph.
and
[graph command](/docs/commands/graph.html) will expand modules by default. You
can use the `-module-depth` parameter to limit the graph.
For example, with a configuration similar to what we've built above, here For example, with a configuration similar to what we've built above, here is what the graph output looks like by default:
is what the graph output looks like by default:
<div class="center"> <div class="center">
![Terraform Expanded Module Graph](docs/module_graph_expand.png) ![Terraform Expanded Module Graph](docs/module_graph_expand.png)
</div> </div>
But if we set `-module-depth=0`, the graph will look like this: If instead we set `-module-depth=0`, the graph will look like this:
<div class="center"> <div class="center">
![Terraform Module Graph](docs/module_graph.png) ![Terraform Module Graph](docs/module_graph.png)
</div> </div>
Other commands work similarly with modules. Note that the `-module-depth` Other commands work similarly with modules. Note that the `-module-depth` flag is purely a formatting flag; it doesn't affect what modules are created or not.
flag is purely a formatting flag; it doesn't affect what modules are created
or not.
## Tainting resources within a module ## Tainting resources within a module
The [taint command](/docs/commands/taint.html) can be used to _taint_ The [taint command](/docs/commands/taint.html) can be used to _taint_ specific resources within a module:
specific resources within a module:
``` ```
terraform taint -module=salt_master aws_instance.salt_master terraform taint -module=salt_master aws_instance.salt_master
``` ```
It is not (yet) possible to taint an entire module. It is currently not possible to taint an entire module.