github.com/pmcatominey/terraform@v0.7.0-rc2.0.20160708105029-1401a52a5cc5/website/source/docs/modules/usage.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Using Modules"
     4  sidebar_current: "docs-modules-usage"
     5  description: Using modules in Terraform is very similar to defining resources.
     6  ---
     7  
     8  # Module Usage
     9  
    10  Using modules in Terraform is very similar to defining resources:
    11  
    12  ```
    13  module "consul" {
    14  	source = "github.com/hashicorp/consul/terraform/aws"
    15  	servers = 3
    16  }
    17  ```
    18  
    19  You can view the full documentation for the syntax of configuring
    20  modules [here](/docs/configuration/modules.html).
    21  
    22  As you can see, it is very similar to defining resources, with the exception
    23  that we don't specify a type, and just a name. This name can be used elsewhere
    24  in the configuration to reference the module and its variables.
    25  
    26  The existence of the above configuration will tell Terraform to create
    27  the resources in the "consul" module which can be found on GitHub with the
    28  given URL. Just like a resource, the module configuration can be deleted
    29  to remove the module.
    30  
    31  ## Multiple instances of a module
    32  
    33  You can instantiate a module multiple times.
    34  
    35  ```
    36  # my_buckets.tf
    37  module "assets_bucket" {
    38    source = "./publish_bucket"
    39    name = "assets"
    40  }
    41  
    42  module "media_bucket" {
    43    source = "./publish_bucket"
    44    name = "media"
    45  }
    46  ```
    47  ```
    48  # publish_bucket/bucket-and-cloudfront.tf
    49  
    50  variable "name" {} # this is the input parameter of the module
    51  
    52  resource "aws_s3_bucket" "the_bucket" {
    53  ...
    54  
    55  resource "aws_iam_user" "deploy_user" {
    56  ...
    57  ```
    58  
    59  In this example you can provide module implementation in the `./publish_bucket`
    60  subfolder - define there, how to create a bucket resource, set access and
    61  caching rules, create e.g. a CloudFront resource, which wraps the bucket and
    62  all the other implementation details, which are common to you project.
    63  
    64  In the snippet above, you now use your module definition twice. The string
    65  after the `module` keyword is a name of the instance of the module.
    66  
    67  Note: the resource names in your implementation get prefixed by the
    68  `module.<module-instance-name>` when instantiated. Example: your `publish_bucket`
    69  implementation creates `aws_s3_bucket.the_bucket` and `aws_iam_access_key.deploy_user`.
    70  The full name of the resulting resources will be `module.assets_bucket.aws_s3_bucket.the_bucket`
    71  and `module.assets_bucket.aws_iam_access_key.deploy_user`. So beware, if you
    72  extract your implementation to a module. The resource names will change and
    73  this will lead to destroying s3 buckets and creating new ones - so always
    74  check with `tf plan` before running `tf apply`. 
    75  
    76  ## Source
    77  
    78  The only required configuration key is the `source` parameter. The value of
    79  this tells Terraform where the module can be downloaded, updated, etc.
    80  Terraform comes with support for a variety of module sources. These
    81  are documented on a [separate page](/docs/modules/sources.html).
    82  
    83  Prior to running any command such as `plan` with a configuration that
    84  uses modules, you'll have to [get](/docs/commands/get.html) the modules.
    85  This is done using the [get command](/docs/commands/get.html).
    86  
    87  ```
    88  $ terraform get
    89  ...
    90  ```
    91  
    92  This command will download the modules if they haven't been already.
    93  By default, the command will not check for updates, so it is safe (and fast)
    94  to run multiple times. You can use the `-update` flag to check and download
    95  updates.
    96  
    97  ## Configuration
    98  
    99  The parameters used to configure modules, such as the `servers` parameter
   100  above, map directly to [variables](/docs/configuration/variables.html) within
   101  the module itself. Therefore, you can quickly discover all the configuration
   102  for a module by inspecting the source of it very easily.
   103  
   104  Additionally, because these map directly to variables, they're always simple
   105  key/value pairs. Modules can't have complex variable inputs.
   106  
   107  ## Dealing with parameters of the list type
   108  
   109  Variables are currently unable to hold the list type. Sometimes, though, it's
   110  desirable to parameterize a module's resource with an attribute that is of the
   111  list type, for example `aws_instance.security_groups`. 
   112  
   113  Until a future release broadens the functionality of variables to include list
   114  types, the way to work around this limitation is to pass a delimited string as
   115  a module parameter, and then "unpack" that parameter using
   116  [`split`](/docs/configuration/interpolation.html) interpolation function within
   117  the module definition. 
   118  
   119  Depending on the resource parameter in question, you may have to 
   120  indicate that the unpacked string is actually a list by using list notation.
   121  For example:
   122  
   123  ```
   124  resource_param = ["${split(",", var.CSV_STRING)}"]
   125  ```
   126  
   127  ## Outputs
   128  
   129  Modules can also specify their own [outputs](/docs/configuration/outputs.html).
   130  These outputs can be referenced in other places in your configuration.
   131  For example:
   132  
   133  ```
   134  resource "aws_instance" "client" {
   135    ami = "ami-408c7f28"
   136    instance_type = "t1.micro"  
   137    availability_zone = "${module.consul.server_availability_zone}"
   138  }
   139  ```
   140  
   141  This purposely is very similar to accessing resource attributes. But instead
   142  of mapping to a resource, the variable in this case maps to an output of
   143  a module.
   144  
   145  Just like resources, this will create a dependency from the `aws_instance.client`
   146  resource to the module, so the module will be built first.
   147  
   148  ## Plans and Graphs
   149  
   150  With modules, commands such as the [plan command](/docs/commands/plan.html)
   151  and
   152  [graph command](/docs/commands/graph.html) will expand modules by default. You
   153  can use the `-module-depth` parameter to limit the graph.
   154  
   155  For example, with a configuration similar to what we've built above, here
   156  is what the graph output looks like by default:
   157  
   158  <div class="center">
   159  ![Terraform Expanded Module Graph](docs/module_graph_expand.png)
   160  </div>
   161  
   162  But if we set `-module-depth=0`, the graph will look like this:
   163  
   164  <div class="center">
   165  ![Terraform Module Graph](docs/module_graph.png)
   166  </div>
   167  
   168  Other commands work similarly with modules. Note that the `-module-depth`
   169  flag is purely a formatting flag; it doesn't affect what modules are created
   170  or not.
   171  
   172  ## Tainting resources within a module
   173  
   174  The [taint command](/docs/commands/taint.html) can be used to _taint_
   175  specific resources within a module:
   176  
   177  ```
   178  terraform taint -module=salt_master aws_instance.salt_master
   179  ```
   180  
   181  It is not (yet) possible to taint an entire module.