diff --git a/website/source/docs/modules/sources.html.markdown b/website/source/docs/modules/sources.html.markdown index 89d774c60..ff5fbff2c 100644 --- a/website/source/docs/modules/sources.html.markdown +++ b/website/source/docs/modules/sources.html.markdown @@ -2,20 +2,14 @@ layout: "docs" page_title: "Module Sources" sidebar_current: "docs-modules-sources" -description: |- - As documented in usage, the only required parameter when using a module is the `source` parameter which tells Terraform where the module can be found and what constraints to put on the module if any (such as branches for Git, versions, etc.). +description: Explains the use of the source parameter, which tells Terraform where modules can be found. --- # Module Sources -As documented in [usage](/docs/modules/usage.html), the only required -parameter when using a module is the `source` parameter which tells Terraform -where the module can be found and what constraints to put on the module -if any (such as branches for Git, versions, etc.). +As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`. The `source` parameter tells Terraform where the module can be found and what constraints to put on the module. Constraints can include a specific version or Git branch. -Terraform manages modules for you: it downloads them, organizes them -on disk, checks for updates, etc. Terraform uses this source parameter for -the download/update of modules. +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. Terraform supports the following sources: @@ -29,18 +23,11 @@ Terraform supports the following sources: * HTTP URLs -Note that all remote modules are git-based. The `HTTP URL` source redirects terraform to use another one of the sources. - Each is documented further below. ## Local File Paths -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. - -An example is shown below: +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: ``` module "consul" { @@ -48,15 +35,11 @@ module "consul" { } ``` -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 instantly available. +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. ## GitHub -Terraform will automatically recognize GitHub URLs and turn them into -the proper Git repository. The syntax is simple: +Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple: ``` module "consul" { @@ -72,28 +55,17 @@ module "consul" { } ``` -**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. +**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. -GitHub source URLs will require that Git is installed on your system -and that you have the proper access to the repository. +GitHub source URLs require that Git is installed on your system and that you have access to the repository. -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. +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. -#### Private GitHub Repos +### Private GitHub Repos -If you need Terraform to be able to fetch modules from private GitHub repos on -a remote machine (like a Atlas 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. +If you need Terraform to be able to fetch modules from private GitHub repos on a remote machine (like Atlas 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. -First, create a [machine -user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) -with access to read from the private repo in question, then embed this user's -credentials into the source field: +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: ``` module "private-infra" { @@ -101,20 +73,15 @@ module "private-infra" { } ``` -Note that 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 lifted. +**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. ## BitBucket -Terraform will automatically recognize BitBucket URLs and turn them into -the proper Git or Mercurial repository. An example: +Terraform will automatically recognize BitBucket URLs and turn them into a link to the specific Git or Mercurial repository, for example: ``` module "consul" { - source = "bitbucket.org/hashicorp/example" + source = "bitbucket.org/hashicorp/consul" } ``` @@ -122,123 +89,79 @@ Subdirectories within the repository can also be referenced: ``` module "consul" { - source = "bitbucket.org/hashicorp/example//subdir" + source = "bitbucket.org/hashicorp/consul//subdir" } ``` -**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. +**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. -BitBucket URLs will require that Git or Mercurial is installed on your -system, depending on the source URL. +BitBucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository. ## Generic Git Repository -Generic Git repositories are also supported. The value of `source` in this -case should be a complete Git-compatible URL. Using Git requires that -Git is installed on your system. Example: +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. ``` module "consul" { - source = "git://hashicorp.com/module.git" + source = "git://hashicorp.com/consul.git" } ``` -You can also use protocols such as HTTP or SSH, but you'll have to hint -to Terraform (using the forced source type syntax documented below) to use -Git: +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: ``` -// force https source module "consul" { - source = "git::https://hashicorp.com/module.git" + source = "git::https://hashicorp.com/consul.git" } -// force ssh source module "ami" { source = "git::ssh://git@github.com/owner/repo.git" } ``` -URLs for Git repositories (of any protocol) support the following query -parameters: +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. + +The URLs for Git repositories support the following query parameters: * `ref` - The ref to checkout. This can be a branch, tag, commit, etc. -An example of using these parameters is shown below: - ``` module "consul" { - source = "git::https://hashicorp.com/module.git?ref=master" + source = "git::https://hashicorp.com/consul.git?ref=master" } ``` ## Generic Mercurial Repository -Generic Mercurial repositories are supported. The value of `source` in this -case should be a complete Mercurial-compatible URL. Using Mercurial requires that -Mercurial is installed on your system. Example: +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::`. ``` module "consul" { - source = "hg::http://hashicorp.com/module.hg" + source = "hg::http://hashicorp.com/consul.hg" } ``` -In the case of above, we used the forced source type syntax documented below. -Mercurial repositories require this. - -URLs for Mercurial repositories (of any protocol) support the following query -parameters: +URLs for Mercurial repositories support the following query parameters: * `rev` - The rev to checkout. This can be a branch, tag, commit, etc. +``` +module "consul" { + source = "hg::http://hashicorp.com/consul.hg?ref=master" +} +``` + ## HTTP URLs -An HTTP URL can be used to redirect Terraform to get the module source from -one of the other sources. For HTTP URLs (SSL is supported, as well), -Terraform will make a GET request to the given URL. -An additional GET parameter `terraform-get=1` will be appended, allowing +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 you to optionally render the page differently when Terraform is requesting it. -Terraform then looks for the resulting module URL in the following order. +Terraform then looks for the resulting module URL in the following order: -First, if a header `X-Terraform-Get` is present, then it should contain -the source URL of the actual module. This will be used. +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. -If the header isn't present, Terraform will look for a `` tag -with the name of "terraform-get". The value will be used as the source -URL. - -Example: +2. Terraform will look for a `` tag with the name of `terraform-get`, for example: ``` ``` - -## Forced Source Type - -In a couple places above, we've referenced "forced source type." Forced -source type is a syntax added to URLs that allow you to force a specific -method for download/updating the module. It is used to disambiguate URLs. - -For example, the source "http://hashicorp.com/foo.git" could just as -easily be a plain HTTP URL as it might be a Git repository speaking the -HTTP protocol. The forced source type syntax is used to force Terraform -one way or the other. - -Example: - -``` -module "consul" { - source = "git::http://hashicorp.com/foo.git" -} -``` - -The above will force Terraform to get the module using Git, despite it -being an HTTP URL. - -If a forced source type isn't specified, Terraform will match the exact -protocol if it supports it. It will not try multiple methods. In the case -above, it would've used the HTTP method.