github.com/trawler/terraform@v0.10.8-0.20171106022149-4b1c7a1d9b48/website/docs/modules/sources.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "Module Sources" 4 sidebar_current: "docs-modules-sources" 5 description: Explains the use of the source parameter, which tells Terraform where modules can be found. 6 --- 7 8 # Module Sources 9 10 As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`. 11 12 The `source` parameter tells Terraform where the module can be found. 13 Terraform manages modules for you: it downloads them, organizes them on disk, checks for updates, etc. Terraform uses this `source` parameter to determine where it should retrieve and update modules from. 14 15 Terraform supports the following sources: 16 17 * Local file paths 18 19 * [Terraform Registry](/docs/registry/index.html) 20 21 * GitHub 22 23 * Bitbucket 24 25 * Generic Git, Mercurial repositories 26 27 * HTTP URLs 28 29 * S3 buckets 30 31 Each is documented further below. 32 33 ## Local File Paths 34 35 The easiest source is the local file path. For maximum portability, this should be a relative file path into a subdirectory. This allows you to organize your Terraform configuration into modules within one repository, for example: 36 37 ```hcl 38 module "consul" { 39 source = "./consul" 40 } 41 ``` 42 43 Updates for file paths are automatic: when "downloading" the module using the [get command](/docs/commands/get.html), Terraform will create a symbolic link to the original directory. Therefore, any changes are automatically available. 44 45 ## Terraform Registry 46 47 The [Terraform Registry](https://registry.terraform.io) is an index of modules 48 written by the Terraform community. 49 The Terraform Registry is the easiest 50 way to get started with Terraform and to find modules to start with. 51 The registry is integrated directly into Terraform: 52 53 ```hcl 54 module "consul" { 55 source = "hashicorp/consul/aws" 56 } 57 ``` 58 59 The above example would use the 60 [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws) 61 from the public registry. 62 63 You can learn more about the registry at the 64 [Terraform Registry documentation section](/docs/registry/index.html). 65 66 ## GitHub 67 68 Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple: 69 70 ```hcl 71 module "consul" { 72 source = "github.com/hashicorp/example" 73 } 74 ``` 75 76 Subdirectories within the repository can also be referenced: 77 78 ```hcl 79 module "consul" { 80 source = "github.com/hashicorp/example//subdir" 81 } 82 ``` 83 84 These will fetch the modules using HTTPS. If you want to use SSH instead: 85 86 ```hcl 87 module "consul" { 88 source = "git@github.com:hashicorp/example.git//subdir" 89 } 90 ``` 91 92 **Note:** The double-slash, `//`, is important. It is what tells Terraform that that is the separator for a subdirectory, and not part of the repository itself. 93 94 GitHub source URLs require that Git is installed on your system and that you have access to the repository. 95 96 You can use the same parameters to GitHub repositories as you can generic Git repositories (such as tags or branches). See the documentation for generic Git repositories for more information. 97 98 ### Private GitHub Repos 99 100 If you need Terraform to be able to fetch modules from private GitHub repos on a remote machine (like Terraform Enterprise or a CI server), you'll need to provide Terraform with credentials that can be used to authenticate as a user with read access to the private repo. 101 102 First, create a [machine user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) on GitHub with read access to the private repo in question, then embed this user's credentials into the `source` parameter: 103 104 ```hcl 105 module "private-infra" { 106 source = "git::https://MACHINE-USER:MACHINE-PASS@github.com/org/privatemodules//modules/foo" 107 } 108 ``` 109 110 **Note:** Terraform does not yet support interpolations in the `source` field, so the machine username and password will have to be embedded directly into the `source` string. You can track [GH-1439](https://github.com/hashicorp/terraform/issues/1439) to learn when this limitation is addressed. 111 112 ## Bitbucket 113 114 Terraform will automatically recognize public Bitbucket URLs and turn them into a link to the specific Git or Mercurial repository, for example: 115 116 ```hcl 117 module "consul" { 118 source = "bitbucket.org/hashicorp/consul" 119 } 120 ``` 121 122 Subdirectories within the repository can also be referenced: 123 124 ```hcl 125 module "consul" { 126 source = "bitbucket.org/hashicorp/consul//subdir" 127 } 128 ``` 129 130 **Note:** The double-slash, `//`, is important. It is what tells Terraform that this is the separator for a subdirectory, and not part of the repository itself. 131 132 Bitbucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository. 133 134 ## Private Bitbucket Repos 135 Private bitbucket repositories must be specified similar to the Generic Git Respository section below. 136 137 ```hcl 138 module "consul" { 139 source = "git::https://bitbucket.org/foocompany/module_name.git" 140 } 141 ``` 142 143 You can also specify branches and version withs the ?ref query 144 145 ```hcl 146 module "consul" { 147 source = "git::https://bitbucket.org/foocompany/module_name.git?ref=hotfix" 148 } 149 ``` 150 151 You will need to run a `terraform get -update=true` if you want to pull the latest versions. This can be handy when you are rapidly iterating on a module in development. 152 153 ## Generic Git Repository 154 155 Generic Git repositories are also supported. The value of `source` in this case should be a complete Git-compatible URL. Using generic Git repositories requires that Git is installed on your system. 156 157 ```hcl 158 module "consul" { 159 source = "git://hashicorp.com/consul.git" 160 } 161 ``` 162 163 You can also use protocols such as HTTP or SSH to reference a module, but you'll have specify to Terraform that it is a Git module, by prefixing the URL with `git::` like so: 164 165 ```hcl 166 module "consul" { 167 source = "git::https://hashicorp.com/consul.git" 168 } 169 170 module "ami" { 171 source = "git::ssh://git@github.com/owner/repo.git" 172 } 173 ``` 174 175 If you do not specify the type of `source` then Terraform will attempt to use the closest match, for example assuming `https://hashicorp.com/consul.git` is a HTTP URL. 176 177 The URLs for Git repositories support the following query parameters: 178 179 * `ref` - The ref to checkout. This can be a branch, tag, commit, etc. 180 181 ```hcl 182 module "consul" { 183 source = "git::https://hashicorp.com/consul.git?ref=master" 184 } 185 ``` 186 187 Terraform will cache the module locally by default `terraform get` is run, so successive updates to master or a specified branch will not be factored into future plans. Run `terraform get -update=true` to get the latest version of the branch. This is handy in development, but potentially bothersome in production if you don't have control of the repository. 188 189 ## Generic Mercurial Repository 190 191 Generic Mercurial repositories are supported. The value of `source` in this case should be a complete Mercurial-compatible URL. Using generic Mercurial repositories requires that Mercurial is installed on your system. You must tell Terraform that your `source` is a Mercurial repository by prefixing it with `hg::`. 192 193 ```hcl 194 module "consul" { 195 source = "hg::http://hashicorp.com/consul.hg" 196 } 197 ``` 198 199 URLs for Mercurial repositories support the following query parameters: 200 201 * `rev` - The rev to checkout. This can be a branch, tag, commit, etc. 202 203 ```hcl 204 module "consul" { 205 source = "hg::http://hashicorp.com/consul.hg?rev=default" 206 } 207 ``` 208 209 ## HTTP URLs 210 211 An HTTP or HTTPS URL can be used to redirect Terraform to get the module source from one of the other sources. For HTTP URLs, Terraform will make a `GET` request to the given URL. An additional `GET` parameter, `terraform-get=1`, will be appended, allowing 212 you to optionally render the page differently when Terraform is requesting it. 213 214 Terraform then looks for the resulting module URL in the following order: 215 216 1. Terraform will look to see if the header `X-Terraform-Get` is present. The header should contain the source URL of the actual module. 217 218 2. Terraform will look for a `<meta>` tag with the name of `terraform-get`, for example: 219 220 ```html 221 <meta name="terraform-get" content="github.com/hashicorp/example" /> 222 ``` 223 224 ### S3 Bucket 225 226 Terraform can also store modules in an S3 bucket. To access the bucket 227 you must have appropriate AWS credentials in your configuration or 228 available via shared credentials or environment variables. 229 230 There are a variety of S3 bucket addressing schemes, most are 231 [documented in the S3 232 configuration](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro). 233 Here are a couple of examples. 234 235 Using the `s3` protocol. 236 237 ```hcl 238 module "consul" { 239 source = "s3::https://s3-eu-west-1.amazonaws.com/consulbucket/consul.zip" 240 } 241 ``` 242 243 Or directly using the bucket's URL. 244 245 ```hcl 246 module "consul" { 247 source = "consulbucket.s3-eu-west-1.amazonaws.com/consul.zip" 248 } 249 ``` 250 251 252 ## Unarchiving 253 254 Terraform will automatically unarchive files based on the extension of 255 the file being requested (over any protocol). It supports the following 256 archive formats: 257 258 * tar.gz and tgz 259 * tar.bz2 and tbz2 260 * zip 261 * gz 262 * bz2