182 lines
6.0 KiB
Markdown
182 lines
6.0 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Using Modules"
|
|
sidebar_current: "docs-modules-usage"
|
|
description: Using modules in Terraform is very similar to defining resources.
|
|
---
|
|
|
|
# Module Usage
|
|
|
|
Using modules in Terraform is very similar to defining resources:
|
|
|
|
```
|
|
module "consul" {
|
|
source = "github.com/hashicorp/consul/terraform/aws"
|
|
servers = 3
|
|
}
|
|
```
|
|
|
|
You can view the full documentation for the syntax of configuring
|
|
modules [here](/docs/configuration/modules.html).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Multiple instances of a module
|
|
|
|
You can instantiate a module multiple times.
|
|
|
|
```
|
|
# my_buckets.tf
|
|
module "assets_bucket" {
|
|
source = "./publish_bucket"
|
|
name = "assets"
|
|
}
|
|
|
|
module "media_bucket" {
|
|
source = "./publish_bucket"
|
|
name = "media"
|
|
}
|
|
```
|
|
```
|
|
# publish_bucket/bucket-and-cloudfront.tf
|
|
|
|
variable "name" {} # this is the input parameter of the module
|
|
|
|
resource "aws_s3_bucket" "the_bucket" {
|
|
...
|
|
|
|
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 you project.
|
|
|
|
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.
|
|
|
|
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`.
|
|
|
|
## 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).
|
|
|
|
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).
|
|
|
|
```
|
|
$ 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.
|
|
|
|
## 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.
|
|
|
|
Additionally, because these map directly to variables, they're always simple
|
|
key/value pairs. Modules can't have complex variable inputs.
|
|
|
|
## Dealing with parameters of the list type
|
|
|
|
Variables are currently unable to hold the list type. Sometimes, though, it's
|
|
desirable to parameterize a module's resource with an attribute that is of the
|
|
list type, for example `aws_instance.security_groups`.
|
|
|
|
Until a future release broadens the functionality of variables to include list
|
|
types, the way to work around this limitation is to pass a delimited string as
|
|
a module parameter, and then "unpack" that parameter using
|
|
[`split`](/docs/configuration/interpolation.html) interpolation function within
|
|
the module definition.
|
|
|
|
Depending on the resource parameter in question, you may have to
|
|
indicate that the unpacked string is actually a list by using list notation.
|
|
For example:
|
|
|
|
```
|
|
resource_param = ["${split(",", var.CSV_STRING)}"]
|
|
```
|
|
|
|
## 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:
|
|
|
|
```
|
|
resource "aws_instance" "client" {
|
|
ami = "ami-408c7f28"
|
|
instance_type = "t1.micro"
|
|
availability_zone = "${module.consul.server_availability_zone}"
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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">
|
|
|
|
</div>
|
|
|
|
But if we set `-module-depth=0`, the graph will look like this:
|
|
|
|
<div class="center">
|
|
|
|
</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.
|
|
|
|
## Tainting 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.
|