github.com/daveadams/terraform@v0.6.4-0.20160830094355-13ce74975936/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  
    56  resource "aws_iam_user" "deploy_user" {
    57    # ...
    58  }
    59  ```
    60  
    61  In this example you can provide module implementation in the `./publish_bucket`
    62  subfolder - define there, how to create a bucket resource, set access and
    63  caching rules, create e.g. a CloudFront resource, which wraps the bucket and
    64  all the other implementation details, which are common to your project.
    65  
    66  In the snippet above, you now use your module definition twice. The string
    67  after the `module` keyword is a name of the instance of the module.
    68  
    69  Note: the resource names in your implementation get prefixed by the
    70  `module.<module-instance-name>` when instantiated. Example: your `publish_bucket`
    71  implementation creates `aws_s3_bucket.the_bucket` and `aws_iam_access_key.deploy_user`.
    72  The full name of the resulting resources will be `module.assets_bucket.aws_s3_bucket.the_bucket`
    73  and `module.assets_bucket.aws_iam_access_key.deploy_user`. So beware, if you
    74  extract your implementation to a module. The resource names will change and
    75  this will lead to destroying s3 buckets and creating new ones - so always
    76  check with `tf plan` before running `tf apply`.
    77  
    78  ## Source
    79  
    80  The only required configuration key is the `source` parameter. The value of
    81  this tells Terraform where the module can be downloaded, updated, etc.
    82  Terraform comes with support for a variety of module sources. These
    83  are documented on a [separate page](/docs/modules/sources.html).
    84  
    85  Prior to running any command such as `plan` with a configuration that
    86  uses modules, you'll have to [get](/docs/commands/get.html) the modules.
    87  This is done using the [get command](/docs/commands/get.html).
    88  
    89  ```
    90  $ terraform get
    91  ...
    92  ```
    93  
    94  This command will download the modules if they haven't been already.
    95  By default, the command will not check for updates, so it is safe (and fast)
    96  to run multiple times. You can use the `-update` flag to check and download
    97  updates.
    98  
    99  ## Configuration
   100  
   101  The parameters used to configure modules, such as the `servers` parameter
   102  above, map directly to [variables](/docs/configuration/variables.html) within
   103  the module itself. Therefore, you can quickly discover all the configuration
   104  for a module by inspecting the source of it very easily.
   105  
   106  Additionally, because these map directly to variables, module configuration can
   107  have any data type supported by variables, including maps and lists.
   108  
   109  ## Outputs
   110  
   111  Modules can also specify their own [outputs](/docs/configuration/outputs.html).
   112  These outputs can be referenced in other places in your configuration.
   113  For example:
   114  
   115  ```
   116  resource "aws_instance" "client" {
   117    ami               = "ami-408c7f28"
   118    instance_type     = "t1.micro"
   119    availability_zone = "${module.consul.server_availability_zone}"
   120  }
   121  ```
   122  
   123  This purposely is very similar to accessing resource attributes. But instead
   124  of mapping to a resource, the variable in this case maps to an output of
   125  a module.
   126  
   127  Just like resources, this will create a dependency from the `aws_instance.client`
   128  resource to the module, so the module will be built first.
   129  
   130  ## Plans and Graphs
   131  
   132  With modules, commands such as the [plan command](/docs/commands/plan.html)
   133  and
   134  [graph command](/docs/commands/graph.html) will expand modules by default. You
   135  can use the `-module-depth` parameter to limit the graph.
   136  
   137  For example, with a configuration similar to what we've built above, here
   138  is what the graph output looks like by default:
   139  
   140  <div class="center">
   141  ![Terraform Expanded Module Graph](docs/module_graph_expand.png)
   142  </div>
   143  
   144  But if we set `-module-depth=0`, the graph will look like this:
   145  
   146  <div class="center">
   147  ![Terraform Module Graph](docs/module_graph.png)
   148  </div>
   149  
   150  Other commands work similarly with modules. Note that the `-module-depth`
   151  flag is purely a formatting flag; it doesn't affect what modules are created
   152  or not.
   153  
   154  ## Tainting resources within a module
   155  
   156  The [taint command](/docs/commands/taint.html) can be used to _taint_
   157  specific resources within a module:
   158  
   159  ```
   160  terraform taint -module=salt_master aws_instance.salt_master
   161  ```
   162  
   163  It is not (yet) possible to taint an entire module.