github.com/maheshbr/terraform@v0.3.1-0.20141020033300-deec7194a3ea/website/source/intro/getting-started/modules.html.md (about)

     1  ---
     2  layout: "intro"
     3  page_title: "Modules"
     4  sidebar_current: "gettingstarted-modules"
     5  ---
     6  
     7  # Modules
     8  
     9  Up to this point, we've been configuring Terraform by editing Terraform
    10  configurations directly. As our infrastructure grows, this practice has a few
    11  key problems: a lack of organization, a lack of reusability, and difficulties
    12  in management for teams.
    13  
    14  _Modules_ in Terraform are self-contained packages of Terraform configurations
    15  that are managed as a group. Modules are used to create reusable components,
    16  improve organization, and to treat pieces of infrastructure as a black box.
    17  
    18  This section of the getting started will cover the basics of using modules.
    19  Writing modules is covered in more detail in the
    20  [modules documentation](/docs/modules/index.html).
    21  
    22  <div class="alert alert-block alert-warning">
    23  <p>
    24  <strong>Warning:</strong> The examples on this page are
    25  <em>not eligible</em> for the
    26  AWS
    27  <a href="http://aws.amazon.com/free/">free-tier</a>. Do not execute
    28  the examples on this page unless you're willing to spend a small
    29  amount of money.
    30  </p>
    31  </div>
    32  
    33  ## Using Modules
    34  
    35  If you have any instances running from prior steps in the getting
    36  started guide, use `terraform destroy` to destroy them, and remove all
    37  configuration files.
    38  
    39  As an example, we're going to use the
    40  [Consul Terraform module](#)
    41  which will setup a complete [Consul](http://www.consul.io) cluster
    42  for us.
    43  
    44  Create a configuration file with the following contents:
    45  
    46  ```
    47  module "consul" {
    48  	source = "github.com/hashicorp/consul/terraform/aws"
    49  
    50  	key_name = "AWS SSH KEY NAME"
    51  	key_path = "PATH TO ABOVE PRIVATE KEY"
    52  	region = "AWS REGION"
    53  	servers = "3"
    54  }
    55  ```
    56  
    57  The `module` block tells Terraform to create and manage a module. It is
    58  very similar to the `resource` block. It has a logical name -- in this
    59  case "consul" -- and a set of configurations.
    60  
    61  The `source` configuration is the only mandatory key for modules. It tells
    62  Terraform where the module can be retrieved. Terraform automatically
    63  downloads and manages modules for you. For our example, we're getting the
    64  module directly from GitHub. Terraform can retrieve modules from a variety
    65  of sources including Git, Mercurial, HTTP, and file paths.
    66  
    67  The other configurations are parameters to our module. Please fill them
    68  in with the proper values.
    69  
    70  ## Planning and Apply Modules
    71  
    72  With the modules downloaded, we can now plan and apply it. If you run
    73  `terraform plan`, you should see output similar to below:
    74  
    75  ```
    76  $ terraform plan
    77  TODO
    78  ```
    79  
    80  As you can see, the module is treated like a black box. In the plan, Terraform
    81  shows the module managed as a whole. It does not show what resources within
    82  the module will be created. If you care, you can see that by specifying
    83  a `-module-depth=-1` flag.
    84  
    85  Next, run `terraform apply` to create the module. Note that as we warned above,
    86  the resources this module creates are outside of the AWS free tier, so this
    87  will have some cost associated with it.
    88  
    89  ```
    90  $ terraform apply
    91  TODO
    92  ```
    93  
    94  After a few minutes, you'll have a three server Consul cluster up and
    95  running! Without any knowledge of how Consul works, how to install Consul,
    96  or how to configure Consul into a cluster, you've created a real cluster in
    97  just minutes.
    98  
    99  ## Module Outputs
   100  
   101  Just as we parameterized the module with configurations such as
   102  `servers` above, modules can also output information (just like a resource).
   103  
   104  You'll have to reference the module's code or documentation to know what
   105  outputs it supports for now, but for this guide we'll just tell you that the
   106  Consul module has an output named `server_address` that has the address of
   107  one of the Consul servers that was setup.
   108  
   109  To reference this, we'll just put it into our own output variable. But this
   110  value could be used anywhere: in another resource, to configure another
   111  provider, etc.
   112  
   113  ```
   114  output "consul_address" {
   115  	value = "${module.consul.server_address}"
   116  }
   117  ```
   118  
   119  The syntax for referencing module outputs should be very familiar. The
   120  syntax is `${module.NAME.ATTRIBUTE}`. The `NAME` is the logical name
   121  we assigned earlier, and the `ATTRIBUTE` is the output attribute.
   122  
   123  If you run `terraform apply` again, Terraform should make no changes, but
   124  you'll now see the "consul\_address" output with the address of our Consul
   125  server.
   126  
   127  ## Next
   128  
   129  For more information on modules, the types of sources supported, how
   130  to write modules, and more, read the in depth
   131  [module documentation](/docs/modules/index.html).
   132  
   133  We've now concluded the getting started guide, however
   134  there are a number of [next steps](/intro/getting-started/next-steps.html)
   135  to get started with Terraform.