github.com/bengesoff/terraform@v0.3.1-0.20141018223233-b25a53629922/website/source/docs/modules/usage.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Using Modules"
     4  sidebar_current: "docs-modules-usage"
     5  ---
     6  
     7  # Module Usage
     8  
     9  Using modules in Terraform is very similar to defining resources:
    10  
    11  ```
    12  module "consul" {
    13  	source = "github.com/hashicorp/consul/terraform/aws"
    14  	servers = 3
    15  }
    16  ```
    17  
    18  You can view the full documentation for the syntax of configuring
    19  modules [here](/docs/configuration/modules.html).
    20  
    21  As you can see, it is very similar to defining resources, with the exception
    22  that we don't specify a type, and just a name. This name can be used elsewhere
    23  in the configuration to reference the module and its variables.
    24  
    25  The existence of the above configuration will tell Terraform to create
    26  the resources in the "consul" module which can be found on GitHub with the
    27  given URL. Just like a resource, the module configuration can be deleted
    28  to remove the module.
    29  
    30  ## Source
    31  
    32  The only required configuration key is the `source` parameter. The value of
    33  this tells Terraform where the module can be downloaded, updated, etc.
    34  Terraform comes with support for a variety of module sources. These
    35  are documented on a [separate page](/docs/modules/sources.html).
    36  
    37  Prior to running any command such as `plan` with a configuration that
    38  uses modules, you'll have to [get](/docs/commands/get.html) the modules.
    39  This is done using the [get command](/docs/commands/get.html).
    40  
    41  ```
    42  $ terraform get
    43  ...
    44  ```
    45  
    46  This command will download the modules if they haven't been already.
    47  By default, the command will not check for updates, so it is safe (and fast)
    48  to run multiple times. You can use the `-u` flag to check and download
    49  updates.
    50  
    51  ## Configuration
    52  
    53  The parameters used to configure modules, such as the `servers` parameter
    54  above, map directly to [variables](/docs/configuration/variables.html) within
    55  the module itself. Therefore, you can quickly discover all the configuration
    56  for a module by inspecting the source of it very easily.
    57  
    58  Additionally, because these map directly to variables, they're always simple
    59  key/value pairs. Modules can't have complex variable inputs.
    60  
    61  ## Outputs
    62  
    63  Modules can also specify their own [outputs](/docs/configuration/outputs.html).
    64  These outputs can be referenced in other places in your configuration.
    65  For example:
    66  
    67  ```
    68  resource "aws_instance" "client" {
    69  	ami = "ami-123456"
    70  	instance_type = "m1.small"
    71  	availability_zone = "${module.consul.server_availability_zone}"
    72  }
    73  ```
    74  
    75  This purposely is very similar to accessing resource attributes. But instead
    76  of mapping to a resource, the variable in this case maps to an output of
    77  a module.
    78  
    79  Just like resources, this will create a dependency from the `aws_instance.client`
    80  resource to the module, so the module will be built first.
    81  
    82  ## Plans and Graphs
    83  
    84  With modules, commands such as the [plan command](/docs/commands/plan.html)
    85  and
    86  [graph command](/docs/commands/graph.html) will show the module as a single
    87  unit by default. You can use the `-module-depth` parameter to expand this
    88  graph further.
    89  
    90  For example, with a configuration similar to what we've built above, here
    91  is what the graph output looks like by default:
    92  
    93  <div class="center">
    94  <%= image_tag "docs/module_graph.png" %>
    95  </div>
    96  
    97  But if we set `-module-depth=-1`, the graph will look like this:
    98  
    99  <div class="center">
   100  <%= image_tag "docs/module_graph_expand.png" %>
   101  </div>
   102  
   103  Other commands work similarly with modules. Note that the `-module-depth`
   104  flag is purely a formatting flag; it doesn't affect what modules are created
   105  or not.