github.com/nicgrayson/terraform@v0.4.3-0.20150415203910-c4de50829380/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  ## Outputs
    63  
    64  Modules can also specify their own [outputs](/docs/configuration/outputs.html).
    65  These outputs can be referenced in other places in your configuration.
    66  For example:
    67  
    68  ```
    69  resource "aws_instance" "client" {
    70  	ami = "ami-123456"
    71  	instance_type = "m1.small"
    72  	availability_zone = "${module.consul.server_availability_zone}"
    73  }
    74  ```
    75  
    76  This purposely is very similar to accessing resource attributes. But instead
    77  of mapping to a resource, the variable in this case maps to an output of
    78  a module.
    79  
    80  Just like resources, this will create a dependency from the `aws_instance.client`
    81  resource to the module, so the module will be built first.
    82  
    83  ## Plans and Graphs
    84  
    85  With modules, commands such as the [plan command](/docs/commands/plan.html)
    86  and
    87  [graph command](/docs/commands/graph.html) will show the module as a single
    88  unit by default. You can use the `-module-depth` parameter to expand this
    89  graph further.
    90  
    91  For example, with a configuration similar to what we've built above, here
    92  is what the graph output looks like by default:
    93  
    94  <div class="center">
    95  ![Terraform Module Graph](docs/module_graph.png)
    96  </div>
    97  
    98  But if we set `-module-depth=-1`, the graph will look like this:
    99  
   100  <div class="center">
   101  ![Terraform Expanded Module Graph](docs/module_graph_expand.png)
   102  </div>
   103  
   104  Other commands work similarly with modules. Note that the `-module-depth`
   105  flag is purely a formatting flag; it doesn't affect what modules are created
   106  or not.