github.com/bengesoff/terraform@v0.3.1-0.20141018223233-b25a53629922/website/source/docs/modules/sources.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "Module Sources" 4 sidebar_current: "docs-modules-sources" 5 --- 6 7 # Module Sources 8 9 As documented in [usage](/docs/modules/usage.html), the only required 10 parameter when using a module is the `source` paramter which tells Terraform 11 where the module can be found and what constraints to put on the module 12 if any (such as branches for git, versions, etc.). 13 14 Terraform manages modules for you: it downloads them, organizes them 15 on disk, checks for updates, etc. Terraform uses this source parameter for 16 the download/update of modules. 17 18 Terraform supports the following sources: 19 20 * Local file paths 21 22 * GitHub 23 24 * BitBucket 25 26 * Generic Git, Mercurial repositories 27 28 * HTTP URLs 29 30 Each is documented further below. 31 32 ## Local File Paths 33 34 The easiest source is the local file path. For maximum portability, this 35 should be a relative file path into a subdirectory. This allows you to 36 organize your Terraform configuration into modules within one repository, 37 for example. 38 39 An example is shown below: 40 41 ``` 42 module "consul" { 43 source = "./consul" 44 } 45 ``` 46 47 Updates for file paths are automatic: when "downloading" the module 48 using the [get command](/docs/commands/get.html), Terraform will create 49 a symbolic link to the original directory. Therefore, any changes are 50 automatically instantly available. 51 52 ## GitHub 53 54 Terraform will automatically recognize GitHub URLs and turn them into 55 the proper Git repository. The syntax is simple: 56 57 ``` 58 module "consul" { 59 source = "github.com/hashicorp/example" 60 } 61 ``` 62 63 Subdirectories within the repository can also be referenced: 64 65 ``` 66 module "consul" { 67 source = "github.com/hashicorp/example//subdir" 68 } 69 ``` 70 71 **Note:** The double-slash is important. It is what tells Terraform that 72 that is the separator for a subdirectory, and not part of the repository 73 itself. 74 75 GitHub source URLs will require that Git is installed on your system 76 and that you have the proper access to the repository. 77 78 You can use the same parameters to GitHub repositories as you can generic 79 Git repositories (such as tags or branches). See the documentation for generic 80 Git repositories for more information. 81 82 ## BitBucket 83 84 Terraform will automatically recognize BitBucket URLs and turn them into 85 the proper Git or Mercurial repository. An example: 86 87 ``` 88 module "consul" { 89 source = "bitbucket.org/hashicorp/example" 90 } 91 ``` 92 93 Subdirectories within the repository can also be referenced: 94 95 ``` 96 module "consul" { 97 source = "bitbucket.org/hashicorp/example//subdir" 98 } 99 ``` 100 101 **Note:** The double-slash is important. It is what tells Terraform that 102 that is the separator for a subdirectory, and not part of the repository 103 itself. 104 105 BitBucket URLs will require that Git or Mercurial is installed on your 106 system, depending on the source URL. 107 108 ## Generic Git Repository 109 110 Generic Git repositories are also supported. The value of `source` in this 111 case should be a complete Git-compatible URL. Using Git requires that 112 Git is installed on your system. Example: 113 114 ``` 115 module "consul" { 116 source = "git://hashicorp.com/module.git" 117 } 118 ``` 119 120 You can also use protocols such as HTTP or SSH, but you'll have to hint 121 to Terraform (using the forced source type syntax documented below) to use 122 Git: 123 124 ``` 125 module "consul" { 126 source = "git::https://hashicorp.com/module.git" 127 } 128 ``` 129 130 URLs for Git repositories (of any protocol) support the following query 131 parameters: 132 133 * `ref` - The ref to checkout. This can be a branch, tag, commit, etc. 134 135 An example of using these parameters is shown below: 136 137 ``` 138 module "consul" { 139 source = "git::https://hashicorp.com/module.git?ref=master" 140 } 141 ``` 142 143 ## Generic Mercurial Repository 144 145 Generic Mercurial repositories are supported. The value of `source` in this 146 case should be a complete Mercurial-compatible URL. Using Mercurial requires that 147 Mercurial is installed on your system. Example: 148 149 ``` 150 module "consul" { 151 source = "hg::http://hashicorp.com/module.hg" 152 } 153 ``` 154 155 In the case of above, we used the forced source type syntax documented below. 156 Mercurial repositories require this. 157 158 URLs for Mercurial repositories (of any protocol) support the following query 159 parameters: 160 161 * `rev` - The rev to checkout. This can be a branch, tag, commit, etc. 162 163 ## HTTP URLs 164 165 Any HTTP endpoint can serve up Terraform modules. For HTTP URLs (SSL is 166 supported, as well), Terraform will make a GET request to the given URL. 167 An additional GET parameter `terraform-get=1` will be appended, allowing 168 you to optionally render the page differently when Terraform is requesting it. 169 170 Terraform then looks for the resulting module URL in the following order. 171 172 First, if a header `X-Terraform-Get` is present, then it should contain 173 the source URL of the actual module. This will be used. 174 175 If the header isn't present, Terraform will look for a `<meta>` tag 176 with the name of "terraform-get". The value will be used as the source 177 URL. 178 179 ## Forced Source Type 180 181 In a couple places above, we've referenced "forced source type." Forced 182 source type is a syntax added to URLs that allow you to force a specific 183 method for download/updating the module. It is used to disambiguate URLs. 184 185 For example, the source "http://hashicorp.com/foo.git" could just as 186 easily be a plain HTTP URL as it might be a Git repository speaking the 187 HTTP protocol. The forced source type syntax is used to force Terraform 188 one way or the other. 189 190 Example: 191 192 ``` 193 module "consul" { 194 source = "git::http://hashicorp.com/foo.git" 195 } 196 ``` 197 198 The above will force Terraform to get the module using Git, despite it 199 being an HTTP URL. 200 201 If a forced source type isn't specified, Terraform will match the exact 202 protocol if it supports it. It will not try multiple methods. In the case 203 above, it would've used the HTTP method.