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
GitHub
parent
59b67efd8a
commit
4ec435668a
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue