Rewrite of the module usage page
Tidied up the page and fixed some formatting, style and naming issues.
This commit is contained in:
parent
59b67efd8a
commit
862ef46a49
|
@ -16,17 +16,11 @@ module "consul" {
|
|||
}
|
||||
```
|
||||
|
||||
You can view the full documentation for the syntax of configuring
|
||||
modules [here](/docs/configuration/modules.html).
|
||||
You can view the full documentation for configuring modules in the [Module Configuration](/docs/configuration/modules.html) section.
|
||||
|
||||
As you can see, it is very similar to defining resources, with the exception
|
||||
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.
|
||||
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.
|
||||
|
||||
The existence of the above configuration will tell Terraform to create
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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`
|
||||
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 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.
|
||||
|
||||
In the snippet above, you now use your module definition twice. The string
|
||||
after the `module` keyword is a name of the instance of the module.
|
||||
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`.
|
||||
|
||||
Note: the resource names in your implementation get prefixed by the
|
||||
`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`.
|
||||
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`.
|
||||
|
||||
## Source
|
||||
|
||||
The only required configuration key 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 on a [separate page](/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. These
|
||||
are documented in the [Module sources documentation](/docs/modules/sources.html).
|
||||
|
||||
Prior to running any command such as `plan` 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).
|
||||
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).
|
||||
|
||||
```
|
||||
$ terraform get
|
||||
|
@ -92,25 +71,19 @@ $ terraform get
|
|||
```
|
||||
|
||||
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
|
||||
updates.
|
||||
|
||||
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.
|
||||
|
||||
## Configuration
|
||||
|
||||
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
|
||||
for a module by inspecting the source of it very easily.
|
||||
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
|
||||
for a module by inspecting the source of it.
|
||||
|
||||
Additionally, because these map directly to variables, module configuration can
|
||||
have any data type supported by variables, including maps and lists.
|
||||
Additionally, because these map directly to variables, module configuration can have any data type available for variables, including maps and lists.
|
||||
|
||||
## Outputs
|
||||
|
||||
Modules can also specify their own [outputs](/docs/configuration/outputs.html).
|
||||
These outputs can be referenced in other places in your configuration.
|
||||
For example:
|
||||
Modules can also specify their own [outputs](/docs/configuration/outputs.html). These outputs can be referenced in other places in your configuration, for example:
|
||||
|
||||
```
|
||||
resource "aws_instance" "client" {
|
||||
|
@ -120,44 +93,34 @@ resource "aws_instance" "client" {
|
|||
}
|
||||
```
|
||||
|
||||
This purposely is very similar to accessing resource attributes. But instead
|
||||
of mapping to a resource, the variable in this case maps to an output of
|
||||
a module.
|
||||
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.
|
||||
|
||||
Just like resources, this will create a dependency from the `aws_instance.client`
|
||||
resource to the module, so the module will be built first.
|
||||
Just like resources, this will create a dependency from the `aws_instance.client` resource to the module, so the module will be built first.
|
||||
|
||||
## Plans and Graphs
|
||||
|
||||
With modules, 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.
|
||||
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.
|
||||
|
||||
For example, with a configuration similar to what we've built above, here
|
||||
is what the graph output looks like by default:
|
||||
For example, with a configuration similar to what we've built above, here is what the graph output looks like by default:
|
||||
|
||||
<div class="center">
|
||||
![Terraform Expanded Module Graph](docs/module_graph_expand.png)
|
||||
</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">
|
||||
![Terraform Module Graph](docs/module_graph.png)
|
||||
</div>
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Tainting resources within a module
|
||||
|
||||
The [taint command](/docs/commands/taint.html) can be used to _taint_
|
||||
specific resources within a module:
|
||||
The [taint command](/docs/commands/taint.html) can be used to _taint_ specific resources within a module:
|
||||
|
||||
```
|
||||
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.
|
||||
|
|
Loading…
Reference in New Issue