github.com/nicgrayson/terraform@v0.4.3-0.20150415203910-c4de50829380/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](https://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 ... 87 + module.consul 88 4 resource(s) 89 ``` 90 91 As you can see, the module is treated like a black box. In the plan, Terraform 92 shows the module managed as a whole. It does not show what resources within 93 the module will be created. If you care, you can see that by specifying 94 a `-module-depth=-1` flag. 95 96 Next, run `terraform apply` to create the module. Note that as we warned above, 97 the resources this module creates are outside of the AWS free tier, so this 98 will have some cost associated with it. 99 100 ``` 101 $ terraform apply 102 ... 103 Apply complete! Resources: 3 added, 0 changed, 0 destroyed. 104 ``` 105 106 After a few minutes, you'll have a three server Consul cluster up and 107 running! Without any knowledge of how Consul works, how to install Consul, 108 or how to configure Consul into a cluster, you've created a real cluster in 109 just minutes. 110 111 ## Module Outputs 112 113 Just as we parameterized the module with configurations such as 114 `servers` above, modules can also output information (just like a resource). 115 116 You'll have to reference the module's code or documentation to know what 117 outputs it supports for now, but for this guide we'll just tell you that the 118 Consul module has an output named `server_address` that has the address of 119 one of the Consul servers that was setup. 120 121 To reference this, we'll just put it into our own output variable. But this 122 value could be used anywhere: in another resource, to configure another 123 provider, etc. 124 125 ``` 126 output "consul_address" { 127 value = "${module.consul.server_address}" 128 } 129 ``` 130 131 The syntax for referencing module outputs should be very familiar. The 132 syntax is `${module.NAME.ATTRIBUTE}`. The `NAME` is the logical name 133 we assigned earlier, and the `ATTRIBUTE` is the output attribute. 134 135 If you run `terraform apply` again, Terraform should make no changes, but 136 you'll now see the "consul\_address" output with the address of our Consul 137 server. 138 139 ## Next 140 141 For more information on modules, the types of sources supported, how 142 to write modules, and more, read the in depth 143 [module documentation](/docs/modules/index.html). 144 145 We've now concluded the getting started guide, however 146 there are a number of [next steps](/intro/getting-started/next-steps.html) 147 to get started with Terraform.