github.com/handlerbot/terraform@v0.10.0-beta1.0.20180726153736-26b68d98f9cb/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](#local-file-paths) 18 19 * [Terraform Registry](#terraform-registry) 20 21 * [GitHub](#github) 22 23 * [Bitbucket](#bitbucket) 24 25 * Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories 26 27 * [HTTP URLs](#http-urls) 28 29 * [S3 buckets](#s3-bucket) 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. 51 52 The registry is integrated directly into Terraform. You can reference any 53 registry module with a source string of `<NAMESPACE>/<NAME>/<PROVIDER>`. Each 54 module's information page on the registry includes its source string. 55 56 ```hcl 57 module "consul" { 58 source = "hashicorp/consul/aws" 59 version = "0.1.0" 60 } 61 ``` 62 63 The above example would use the 64 [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws) 65 from the public registry. 66 67 Registry modules support versioning. You can provide a specific version, or use 68 flexible [version constraints](/docs/modules/usage.html#module-versions). 69 70 You can learn more about the registry at the 71 [Terraform Registry documentation](/docs/registry/modules/use.html#using-modules). 72 73 ## Private Registries 74 75 [Terraform Enterprise](https://www.hashicorp.com/products/terraform) provides a 76 [private module registry](/docs/enterprise/registry/index.html), to help 77 you share code within your organization. Other services can also provide 78 private registries by implementing [Terraform's registry API](/docs/registry/api.html). 79 80 Source strings for private registry modules are similar to public modules, but 81 also include a hostname. They should follow the format 82 `<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>`. 83 84 ```hcl 85 module "vpc" { 86 source = "app.terraform.io/example_corp/vpc/aws" 87 version = "0.9.3" 88 } 89 ``` 90 91 Modules from private registries support versioning, just like modules from the 92 public Terraform Registry. 93 94 ## GitHub 95 96 Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple: 97 98 ```hcl 99 module "consul" { 100 source = "github.com/hashicorp/example" 101 } 102 ``` 103 104 Subdirectories within the repository can also be referenced: 105 106 ```hcl 107 module "consul" { 108 source = "github.com/hashicorp/example//subdir" 109 } 110 ``` 111 112 These will fetch the modules using HTTPS. If you want to use SSH instead: 113 114 ```hcl 115 module "consul" { 116 source = "git@github.com:hashicorp/example.git//subdir" 117 } 118 ``` 119 120 **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. 121 122 GitHub source URLs require that Git is installed on your system and that you have access to the repository. 123 124 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](#parameters) for more information. 125 126 ### Private GitHub Repos 127 128 If you need Terraform to fetch modules from private GitHub repos, you must provide Terraform with credentials to authenticate as a user with read access to those repos. 129 130 - If you run Terraform only on your local machine, you can specify the module source as an SSH URI (like `git@github.com:hashicorp/example.git`) and Terraform will use your default SSH key to authenticate. 131 - If you use Terraform Enterprise, consider using the private module registry. It makes handling credentials easier, and provides full versioning support. (See [Private Registries](#private-registries) above for more info.) 132 133 If you need to use modules directly from Git, you can use SSH URIs with Terraform Enterprise. You'll need to add an SSH private key to your organization and assign it to any workspace that fetches modules from private repos. [See the Terraform Enterprise docs about SSH keys for cloning modules.](/docs/enterprise/workspaces/ssh-keys.html) 134 - If you need to run Terraform on a remote machine like a CI worker, you either need to write an SSH key to disk and set the `GIT_SSH_COMMAND` environment variable appropriately during the worker's provisioning process, or create a [GitHub machine user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) with read access to the repos in question and embed its credentials into the modules' `source` parameters: 135 136 ```hcl 137 module "private-infra" { 138 source = "git::https://MACHINE-USER:MACHINE-PASS@github.com/org/privatemodules//modules/foo" 139 } 140 ``` 141 142 Note that Terraform does not support interpolations in the `source` parameter of a module, so you must hardcode the machine username and password if using this method. 143 144 ## Bitbucket 145 146 Terraform will automatically recognize public Bitbucket URLs and turn them into a link to the specific Git or Mercurial repository, for example: 147 148 ```hcl 149 module "consul" { 150 source = "bitbucket.org/hashicorp/consul" 151 } 152 ``` 153 154 Subdirectories within the repository can also be referenced: 155 156 ```hcl 157 module "consul" { 158 source = "bitbucket.org/hashicorp/consul//subdir" 159 } 160 ``` 161 162 **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. 163 164 Bitbucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository. 165 166 ## Private Bitbucket Repos 167 Private bitbucket repositories must be specified similar to the [Generic Git Repository](#generic-git-repository) section below. 168 169 ```hcl 170 module "consul" { 171 source = "git::https://bitbucket.org/foocompany/module_name.git" 172 } 173 ``` 174 175 You can also specify branches and version with the `?ref` query, and use HTTPS or SSH: 176 177 ```hcl 178 module "consul" { 179 source = "git::https://bitbucket.org/foocompany/module_name.git?ref=hotfix" 180 } 181 ``` 182 183 ```hcl 184 module "consul" { 185 source = "git::ssh://git@bitbucket.org/foocompany/module_name.git" 186 } 187 ``` 188 189 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. 190 191 ## Generic Git Repository 192 193 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. 194 195 ```hcl 196 module "consul" { 197 source = "git://hashicorp.com/consul.git" 198 } 199 ``` 200 201 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: 202 203 ```hcl 204 module "consul" { 205 source = "git::https://hashicorp.com/consul.git" 206 } 207 208 module "ami" { 209 source = "git::ssh://git@github.com/owner/repo.git" 210 } 211 ``` 212 213 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. 214 215 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. 216 217 ### Parameters 218 219 The URLs for Git repositories support the following query parameters: 220 221 * `ref` - The ref to checkout. This can be a branch, tag, commit, etc. 222 223 ```hcl 224 module "consul" { 225 source = "git::https://hashicorp.com/consul.git?ref=master" 226 } 227 ``` 228 229 ## Generic Mercurial Repository 230 231 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::`. 232 233 ```hcl 234 module "consul" { 235 source = "hg::http://hashicorp.com/consul.hg" 236 } 237 ``` 238 239 URLs for Mercurial repositories support the following query parameters: 240 241 * `rev` - The rev to checkout. This can be a branch, tag, commit, etc. 242 243 ```hcl 244 module "consul" { 245 source = "hg::http://hashicorp.com/consul.hg?rev=default" 246 } 247 ``` 248 249 ## HTTP URLs 250 251 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 252 you to optionally render the page differently when Terraform is requesting it. 253 254 Terraform then looks for the resulting module URL in the following order: 255 256 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. 257 258 2. Terraform will look for a `<meta>` tag with the name of `terraform-get`, for example: 259 260 ```html 261 <meta name="terraform-get" content="github.com/hashicorp/example" /> 262 ``` 263 264 ## S3 Bucket 265 266 Terraform can also store modules in an S3 bucket. To access the bucket 267 you must have appropriate AWS credentials in your configuration or 268 available via shared credentials or environment variables. 269 270 There are a variety of S3 bucket addressing schemes, most are 271 [documented in the S3 272 configuration](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro). 273 Here are a couple of examples. 274 275 Using the `s3` protocol. 276 277 ```hcl 278 module "consul" { 279 source = "s3::https://s3-eu-west-1.amazonaws.com/consulbucket/consul.zip" 280 } 281 ``` 282 283 Or directly using the bucket's URL. 284 285 ```hcl 286 module "consul" { 287 source = "consulbucket.s3-eu-west-1.amazonaws.com/consul.zip" 288 } 289 ``` 290 291 292 ## Unarchiving 293 294 Terraform will automatically unarchive files based on the extension of 295 the file being requested (over any protocol). It supports the following 296 archive formats: 297 298 * tar.gz and tgz 299 * tar.bz2 and tbz2 300 * zip 301 * gz 302 * bz2