github.com/jmbataller/terraform@v0.6.8-0.20151125192640-b7a12e3a580c/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  ## Source
    32  
    33  The only required configuration key is the `source` parameter. The value of
    34  this tells Terraform where the module can be downloaded, updated, etc.
    35  Terraform comes with support for a variety of module sources. These
    36  are documented on a [separate page](/docs/modules/sources.html).
    37  
    38  Prior to running any command such as `plan` with a configuration that
    39  uses modules, you'll have to [get](/docs/commands/get.html) the modules.
    40  This is done using the [get command](/docs/commands/get.html).
    41  
    42  ```
    43  $ terraform get
    44  ...
    45  ```
    46  
    47  This command will download the modules if they haven't been already.
    48  By default, the command will not check for updates, so it is safe (and fast)
    49  to run multiple times. You can use the `-u` flag to check and download
    50  updates.
    51  
    52  ## Configuration
    53  
    54  The parameters used to configure modules, such as the `servers` parameter
    55  above, map directly to [variables](/docs/configuration/variables.html) within
    56  the module itself. Therefore, you can quickly discover all the configuration
    57  for a module by inspecting the source of it very easily.
    58  
    59  Additionally, because these map directly to variables, they're always simple
    60  key/value pairs. Modules can't have complex variable inputs.
    61  
    62  ## Dealing with parameters of the list type
    63  
    64  Variables are currently unable to hold the list type. Sometimes, though, it's
    65  desirable to parameterize a module's resource with an attribute that is of the
    66  list type, for example `aws_instance.security_groups`. 
    67  
    68  Until a future release broadens the functionality of variables to include list
    69  types, the way to work around this limitation is to pass a delimited string as
    70  a module parameter, and then "unpack" that parameter using
    71  [`split`](/docs/configuration/interpolation.html) interpolation function within
    72  the module definition. 
    73  
    74  Depending on the resource parameter in question, you may have to 
    75  indicate that the unpacked string is actually a list by using list notation.
    76  For example:
    77  
    78  ```
    79  resource_param = ["${split(",", var.CSV_STRING)}"]
    80  ```
    81  
    82  ## Outputs
    83  
    84  Modules can also specify their own [outputs](/docs/configuration/outputs.html).
    85  These outputs can be referenced in other places in your configuration.
    86  For example:
    87  
    88  ```
    89  resource "aws_instance" "client" {
    90  	ami = "ami-123456"
    91  	instance_type = "m1.small"
    92  	availability_zone = "${module.consul.server_availability_zone}"
    93  }
    94  ```
    95  
    96  This purposely is very similar to accessing resource attributes. But instead
    97  of mapping to a resource, the variable in this case maps to an output of
    98  a module.
    99  
   100  Just like resources, this will create a dependency from the `aws_instance.client`
   101  resource to the module, so the module will be built first.
   102  
   103  ## Plans and Graphs
   104  
   105  With modules, commands such as the [plan command](/docs/commands/plan.html)
   106  and
   107  [graph command](/docs/commands/graph.html) will show the module as a single
   108  unit by default. You can use the `-module-depth` parameter to expand this
   109  graph further.
   110  
   111  For example, with a configuration similar to what we've built above, here
   112  is what the graph output looks like by default:
   113  
   114  <div class="center">
   115  ![Terraform Module Graph](docs/module_graph.png)
   116  </div>
   117  
   118  But if we set `-module-depth=-1`, the graph will look like this:
   119  
   120  <div class="center">
   121  ![Terraform Expanded Module Graph](docs/module_graph_expand.png)
   122  </div>
   123  
   124  Other commands work similarly with modules. Note that the `-module-depth`
   125  flag is purely a formatting flag; it doesn't affect what modules are created
   126  or not.
   127  
   128  
   129  ## Tainting resources within a module
   130  
   131  The [taint command](/docs/commands/taint.html) can be used to _taint_
   132  specific resources within a module:
   133  
   134  ```
   135  terraform taint -module=salt_master aws_instance.salt_master
   136  ```
   137  
   138  It is not (yet) possible to taint an entire module.