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