github.com/vtorhonen/terraform@v0.9.0-beta2.0.20170307220345-5d894e4ffda7/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 configuring modules in the [Module Configuration](/docs/configuration/modules.html) section.
    20  
    21  As you can see, configuring modules is very similar to defining resources, with the exception that we only specify a name rather than a name and a type. This name can be used elsewhere in the configuration to reference the module and its variables.
    22  
    23  The existence of the above configuration will tell Terraform to create the resources in the `consul` module which can be found on GitHub at the given URL. Just like a resource, the module configuration can be deleted to remove the module.
    24  
    25  ## Multiple instances of a module
    26  
    27  You can instantiate a module multiple times.
    28  
    29  ```
    30  # my_buckets.tf
    31  module "assets_bucket" {
    32    source = "./publish_bucket"
    33    name   = "assets"
    34  }
    35  
    36  module "media_bucket" {
    37    source = "./publish_bucket"
    38    name   = "media"
    39  }
    40  ```
    41  ```
    42  # publish_bucket/bucket-and-cloudfront.tf
    43  
    44  variable "name" {} # this is the input parameter of the module
    45  
    46  resource "aws_s3_bucket" "the_bucket" {
    47    # ...
    48  }
    49  
    50  resource "aws_iam_user" "deploy_user" {
    51    # ...
    52  }
    53  ```
    54  
    55  In this example you define a module in the `./publish_bucket` subdirectory. That module has configuration to create a bucket resource, set access and caching rules. The module wraps the bucket and all the other implementation details required to configure a bucket.
    56  
    57  We can then define the module multiple times in our configuration by naming each instantiation of the module uniquely, here `module "assets_bucket"` and `module "media_bucket"`, whilst specifying the same module `source`.
    58  
    59  The resource names in your module  get prefixed by `module.<module-instance-name>` when instantiated, for example the `publish_bucket` module creates `aws_s3_bucket.the_bucket` and `aws_iam_access_key.deploy_user`. The full name of the resulting resources will be `module.assets_bucket.aws_s3_bucket.the_bucket` and `module.assets_bucket.aws_iam_access_key.deploy_user`. Be cautious of this when extracting configuration from your files into a module, the name of your resources will change and Terraform will potentially destroy and recreate them. Always check your configuration with `terraform plan` before running `terraform apply`.
    60  
    61  ## Source
    62  
    63  The only required configuration key for a module is the `source` parameter. The value of this tells Terraform where the module can be downloaded, updated, etc. Terraform comes with support for a variety of module sources. These
    64  are documented in the [Module sources documentation](/docs/modules/sources.html).
    65  
    66  Prior to running any Terraform command with a configuration that uses modules, you'll have to [get](/docs/commands/get.html) the modules. This is done using the [get command](/docs/commands/get.html).
    67  
    68  ```
    69  $ terraform get
    70  ...
    71  ```
    72  
    73  This command will download the modules if they haven't been already.
    74  
    75  By default, the command will not check for updates, so it is safe (and fast) to run multiple times. You can use the `-update` flag to check and download updates.
    76  
    77  ## Configuration
    78  
    79  The parameters used to configure modules, such as the `servers` parameter above, map directly to [variables](/docs/configuration/variables.html) within the module itself. Therefore, you can quickly discover all the configuration
    80  for a module by inspecting the source of it.
    81  
    82  Additionally, because these map directly to variables, module configuration can have any data type available for variables, including maps and lists.
    83  
    84  ## Outputs
    85  
    86  Modules can also specify their own [outputs](/docs/configuration/outputs.html). These outputs can be referenced in other places in your configuration, for example:
    87  
    88  ```
    89  resource "aws_instance" "client" {
    90    ami               = "ami-408c7f28"
    91    instance_type     = "t1.micro"
    92    availability_zone = "${module.consul.server_availability_zone}"
    93  }
    94  ```
    95  
    96  This purposely is very similar to accessing resource attributes. Instead of mapping to a resource, however, the variable in this case maps to an output of a module.
    97  
    98  Just like resources, this will create a dependency from the `aws_instance.client` resource to the module, so the module will be built first.
    99  
   100  To use module outputs via command line you have to specify the module name before the variable, for example:
   101  
   102  ```
   103  terraform output -module=consul server_availability_zone
   104  ```
   105  
   106  ## Plans and Graphs
   107  
   108  Commands such as the [plan command](/docs/commands/plan.html) and [graph command](/docs/commands/graph.html) will expand modules by default. You can use the `-module-depth` parameter to limit the graph.
   109  
   110  For example, with a configuration similar to what we've built above, here is what the graph output looks like by default:
   111  
   112  <div class="center">
   113  ![Terraform Expanded Module Graph](docs/module_graph_expand.png)
   114  </div>
   115  
   116  If instead we set `-module-depth=0`, the graph will look like this:
   117  
   118  <div class="center">
   119  ![Terraform Module Graph](docs/module_graph.png)
   120  </div>
   121  
   122  Other commands work similarly with modules. Note that the `-module-depth` flag is purely a formatting flag; it doesn't affect what modules are created or not.
   123  
   124  ## Tainting resources within a module
   125  
   126  The [taint command](/docs/commands/taint.html) can be used to _taint_ specific resources within a module:
   127  
   128  ```
   129  terraform taint -module=salt_master aws_instance.salt_master
   130  ```
   131  
   132  It is currently not possible to taint an entire module.