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  142 </div> 143 144 But if we set `-module-depth=0`, the graph will look like this: 145 146 <div class="center"> 147  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.