Cleanup Module Source page

A quick rewrite of the page to make it clearer. Fixed some styling, grammar and formatting issues too.
This commit is contained in:
James Turnbull 2016-10-01 10:18:04 -04:00 committed by GitHub
parent 59b67efd8a
commit 4ec435668a
1 changed files with 39 additions and 116 deletions

View File

@ -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 the module 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<a id="private-github-repos"></a>
### 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 `<meta>` tag
with the name of "terraform-get". The value will be used as the source
URL.
Example:
2. Terraform will look for a `<meta>` tag with the name of `terraform-get`, for example:
```
<meta name=“terraform-get” content="github.com/hashicorp/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.