website: document modules
This commit is contained in:
Mitchell Hashimoto
parent
fdb0239b4e
commit
03f630bdb8
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Command: get"
|
||||
sidebar_current: "docs-commands-get"
|
||||
---
|
||||
|
||||
# Command: get
|
||||
|
||||
The `terraform get` command is used to download and update
|
||||
[modules](/docs/modules/index.html).
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `terraform get [options] [dir]`
|
||||
|
||||
The modules are downloaded into a local `.terraform` folder. This
|
||||
folder should not be committed to version control.
|
||||
|
||||
If a module is already downloaded and the `-update` flag is _not_ set,
|
||||
Terraform will do nothing. As a result, it is safe (and fast) to run this
|
||||
command multiple times.
|
||||
|
||||
The command-line flags are all optional. The list of available flags are:
|
||||
|
||||
* `-update` - If specified, modules that are already downloaded will be
|
||||
checked for updates and the updates will be downloaded if present.
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuring Modules"
|
||||
sidebar_current: "docs-config-modules"
|
||||
---
|
||||
|
||||
# Module Configuration
|
||||
|
||||
Modules are used in Terraform to modularize and encapsulate groups of
|
||||
resources in your infrastructure. For more information on modules, see
|
||||
the dedicated
|
||||
[modules section](/docs/modules/index.html).
|
||||
|
||||
This page assumes you're familiar with the
|
||||
[configuration syntax](/docs/configuration/syntax.html)
|
||||
already.
|
||||
|
||||
## Example
|
||||
|
||||
Module configuration looks like the following:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "github.com/hashicorp/consul/terraform/aws"
|
||||
servers = 5
|
||||
}
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
The `module` block configures a module and tells Terraform to build
|
||||
its resources. Multiple module blocks may be used to configure and use
|
||||
multiple modules.
|
||||
|
||||
The NAME of the module is logical: it is used only to reference the
|
||||
module in other places in the configuration. It has no effect on the
|
||||
source of the module. Therefore, you may name modules whatever you'd like.
|
||||
|
||||
Within the block (the `{ }`) is configuration for the module.
|
||||
The only required key is `source`, which tells Terraform where this module
|
||||
can be downloaded from. Valid source values are covered in more detail
|
||||
in the
|
||||
[module section](/docs/modules/index.html).
|
||||
|
||||
Other configuration within the module are dependent on the module itself.
|
||||
Because module configuration maps directly to
|
||||
[variables](/docs/configuration/variables.html) within the module, they
|
||||
are always simple key and string values. Complex structures are not used
|
||||
for modules.
|
||||
|
||||
## Syntax
|
||||
|
||||
The full syntax is:
|
||||
|
||||
```
|
||||
module NAME {
|
||||
source = SOURCE_URL
|
||||
|
||||
CONFIG ...
|
||||
}
|
||||
```
|
||||
|
||||
where `CONFIG` is:
|
||||
|
||||
```
|
||||
KEY = VALUE
|
||||
```
|
||||
|
|
@ -0,0 +1,95 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Creating Modules"
|
||||
sidebar_current: "docs-modules-create"
|
||||
---
|
||||
|
||||
# Creating Modules
|
||||
|
||||
Creating modules in Terraform is easy. You may want to do this to better
|
||||
organize your code, to make a reusable component, or just to learn more about
|
||||
Terraform. For any reason, if you already know the basics of Terraform,
|
||||
creating a module is a piece of cake.
|
||||
|
||||
Modules in Terraform are just folders with Terraform files. In fact,
|
||||
when you run `terraform apply`, the current working directory holding
|
||||
the Terraform files you're applying comprise what is called the
|
||||
_root module_. It itself is a valid module.
|
||||
|
||||
Therefore, you can enter the source of any module, run `terraform apply`,
|
||||
and expect it to work (assuming you satisfy the required variables, if any).
|
||||
|
||||
## An Example
|
||||
|
||||
Within a folder containing Terraform configurations, create a subfolder
|
||||
"child". In this subfolder, make one empty "main.tf" file. Then, back in
|
||||
the root folder containing the "child" folder, add this to one of the
|
||||
Terraform files:
|
||||
|
||||
```
|
||||
module "child" {
|
||||
source = "./child"
|
||||
}
|
||||
```
|
||||
|
||||
This will work. You've created your first module! You can add resources
|
||||
to the child module to see how that interaction works.
|
||||
|
||||
## Inputs/Outputs
|
||||
|
||||
To make modules more useful than simple isolated containers of Terraform
|
||||
configurations, modules can be configured and also have outputs that can be
|
||||
consumed by the configuration using the module.
|
||||
|
||||
Inputs of a module are [variables](/docs/configuration/variables.html)
|
||||
and outputs are [outputs](/docs/configuration/outputs.html). There is no
|
||||
special syntax to define these, they're defined just like any other
|
||||
variables or outputs.
|
||||
|
||||
In the "child" module we created above, add the following:
|
||||
|
||||
```
|
||||
variable "memory" {}
|
||||
|
||||
output "received" {
|
||||
value = "${var.memory}"
|
||||
}
|
||||
```
|
||||
|
||||
This will create a required variable "memory" and then an output "received"
|
||||
that will simply be the value of the memory variable.
|
||||
|
||||
You can then configure the module and use the output like so:
|
||||
|
||||
```
|
||||
module "child" {
|
||||
source = "./child"
|
||||
|
||||
memory = "1G"
|
||||
}
|
||||
|
||||
output "child_memory" {
|
||||
value = "${module.child.received}"
|
||||
}
|
||||
```
|
||||
|
||||
If you run `apply`, you'll again see that this works.
|
||||
|
||||
And that is all there is to it. Variables and outputs are used to configure
|
||||
modules and provide results. Resources within a module are isolated,
|
||||
and the whole thing is managed as a single unit.
|
||||
|
||||
## Nested Modules
|
||||
|
||||
You can use a module within a module just like you would anywhere else.
|
||||
This module will be hidden from the root user, so you'll have re-expose any
|
||||
variables if you need to, as well as outputs.
|
||||
|
||||
The [get command](/docs/commands/get.html) will automatically get all
|
||||
nested modules as well.
|
||||
|
||||
You don't have to worry about conflicting versions of modules, since
|
||||
Terraform builds isolated subtrees of all dependencies. For example,
|
||||
one module might use version 1.0 of module "foo" and another module
|
||||
might use version 2.0 of module "foo", and this would all work fine
|
||||
within Terraform since the modules are created separately.
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Modules"
|
||||
sidebar_current: "docs-modules"
|
||||
---
|
||||
|
||||
# Modules
|
||||
|
||||
Modules in terraform are self-contained packages of Terraform configurations
|
||||
that are managed as a group. Modules are used to create reusable components
|
||||
in Terraform as well as for basic code organization.
|
||||
|
||||
Modules are very easy to both use and create. Depending on what you're
|
||||
looking to do first, use the navigation on the left to dive into how
|
||||
modules work.
|
||||
|
|
@ -0,0 +1,195 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Module Sources"
|
||||
sidebar_current: "docs-modules-sources"
|
||||
---
|
||||
|
||||
# Module Sources
|
||||
|
||||
As documented in [usage](/docs/modules/usage.html), the only required
|
||||
parameter when using a module is the `source` paramter 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.).
|
||||
|
||||
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 supports the following sources:
|
||||
|
||||
* Local file paths
|
||||
|
||||
* GitHub
|
||||
|
||||
* BitBucket
|
||||
|
||||
* Generic Git, Mercurial repositories
|
||||
|
||||
* HTTP URLs
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "./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.
|
||||
|
||||
## GitHub
|
||||
|
||||
Terraform will automatically recognize GitHub URLs and turn them into
|
||||
the proper Git repository. The syntax is simple:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "github.com/hashicorp/example"
|
||||
}
|
||||
```
|
||||
|
||||
Subdirectories within the repository can also be referenced:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "github.com/hashicorp/example/subdir"
|
||||
}
|
||||
```
|
||||
|
||||
GitHub source URLs will require that Git is installed on your system
|
||||
and that you have the proper 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.
|
||||
|
||||
## BitBucket
|
||||
|
||||
Terraform will automatically recognize BitBucket URLs and turn them into
|
||||
the proper Git or Mercurial repository. An example:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "bitbucket.org/hashicorp/example"
|
||||
}
|
||||
```
|
||||
|
||||
Subdirectories within the repository can also be referenced:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "bitbucket.org/hashicorp/example/subdir"
|
||||
}
|
||||
```
|
||||
|
||||
BitBucket URLs will require that Git or Mercurial is installed on your
|
||||
system, depending on the source URL.
|
||||
|
||||
## 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:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "git://hashicorp.com/module.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:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "git::https://hashicorp.com/module.git"
|
||||
}
|
||||
```
|
||||
|
||||
URLs for Git repositories (of any protocol) 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"
|
||||
}
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "hg::http://hashicorp.com/module.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:
|
||||
|
||||
* `rev` - The rev to checkout. This can be a branch, tag, commit, etc.
|
||||
|
||||
## HTTP URLs
|
||||
|
||||
Any HTTP endpoint can serve up Terraform modules. 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
|
||||
you to optionally render the page differently when Terraform is requesting it.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
|
@ -0,0 +1,105 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Using Modules"
|
||||
sidebar_current: "docs-modules-usage"
|
||||
---
|
||||
|
||||
# Module Usage
|
||||
|
||||
Using modules in Terraform is very similar to defining resources:
|
||||
|
||||
```
|
||||
module "consul" {
|
||||
source = "github.com/hashicorp/consul/terraform/aws"
|
||||
servers = 3
|
||||
}
|
||||
```
|
||||
|
||||
You can view the full documentation for the syntax of configuring
|
||||
modules [here](/docs/configuration/modules.html).
|
||||
|
||||
As you can see, it is very similar to defining resources, with the exception
|
||||
that we don't specify a type, and just a name. This name can be used elsewhere
|
||||
in the configuration to reference the module and its variables.
|
||||
|
||||
The existence of the above configuration will tell Terraform to create
|
||||
the resources in the "consul" module which can be found on GitHub with the
|
||||
given URL. Just like a resource, the module configuration can be deleted
|
||||
to remove the module.
|
||||
|
||||
## Source
|
||||
|
||||
The only required configuration key is the `source` parameter. The value of
|
||||
this tells Terraform where the module can be downloaded, updated, etc.
|
||||
Terraform comes with support for a variety of module sources. These
|
||||
are documented on a [separate page](/docs/modules/sources.html).
|
||||
|
||||
Prior to running any command such as `plan` with a configuration that
|
||||
uses modules, you'll have to [get](/docs/commands/get.html) the modules.
|
||||
This is done using the [get command](/docs/commands/get.html).
|
||||
|
||||
```
|
||||
$ terraform get
|
||||
...
|
||||
```
|
||||
|
||||
This command will download the modules if they haven't been already.
|
||||
By default, the command will not check for updates, so it is safe (and fast)
|
||||
to run multiple times. You can use the `-u` flag to check and download
|
||||
updates.
|
||||
|
||||
## Configuration
|
||||
|
||||
The parameters used to configure modules, such as the `servers` parameter
|
||||
above, map directly to [variables](/docs/configuration/variables.html) within
|
||||
the module itself. Therefore, you can quickly discover all the configuration
|
||||
for a module by inspecting the source of it very easily.
|
||||
|
||||
Additionally, because these map directly to variables, they're always simple
|
||||
key/value pairs. Modules can't have complex variable inputs.
|
||||
|
||||
## Outputs
|
||||
|
||||
Modules can also specify their own [outputs](/docs/configuration/outputs.html).
|
||||
These outputs can be referenced in other places in your configuration.
|
||||
For example:
|
||||
|
||||
```
|
||||
resource "aws_instance" "client" {
|
||||
ami = "ami-123456"
|
||||
instance_type = "m1.small"
|
||||
availability_zone = "${module.consul.server_availability_zone}"
|
||||
}
|
||||
```
|
||||
|
||||
This purposely is very similar to accessing resource attributes. But instead
|
||||
of mapping to a resource, the variable in this case maps to an output of
|
||||
a module.
|
||||
|
||||
Just like resources, this will create a dependency from the `aws_instance.client`
|
||||
resource to the module, so the module will be built first.
|
||||
|
||||
## Plans and Graphs
|
||||
|
||||
With modules, commands such as the [plan command](/docs/commands/plan.html)
|
||||
and
|
||||
[graph command](/docs/commands/graph.html) will show the module as a single
|
||||
unit by default. You can use the `-module-depth` parameter to expand this
|
||||
graph further.
|
||||
|
||||
For example, with a configuration similar to what we've built above, here
|
||||
is what the graph output looks like by default:
|
||||
|
||||
<div class="center">
|
||||
<img src="/images/docs/module_graph.png">
|
||||
</div>
|
||||
|
||||
But if we set `-module-depth=-1`, the graph will look like this:
|
||||
|
||||
<div class="center">
|
||||
<img src="/images/docs/module_graph_expand.png">
|
||||
</div>
|
||||
|
||||
Other commands work similarly with modules. Note that the `-module-depth`
|
||||
flag is purely a formatting flag; it doesn't affect what modules are created
|
||||
or not.
|
||||
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
|
|
@ -41,6 +41,10 @@
|
|||
<a href="/docs/configuration/outputs.html">Outputs</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-config-modules") %>>
|
||||
<a href="/docs/configuration/modules.html">Modules</a>
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
|
@ -51,6 +55,10 @@
|
|||
<a href="/docs/commands/apply.html">apply</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-get") %>>
|
||||
<a href="/docs/commands/get.html">get</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-graph") %>>
|
||||
<a href="/docs/commands/graph.html">graph</a>
|
||||
</li>
|
||||
|
|
@ -131,6 +139,23 @@
|
|||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-modules") %>>
|
||||
<a href="/docs/modules/index.html">Modules</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-modules-usage") %>>
|
||||
<a href="/docs/modules/usage.html">Usage</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-modules-sources") %>>
|
||||
<a href="/docs/modules/sources.html">Sources</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-modules-create") %>>
|
||||
<a href="/docs/modules/create.html">Creating Modules</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-plugins") %>>
|
||||
<a href="/docs/plugins/index.html">Plugins</a>
|
||||
<ul class="nav">
|
||||
|
|
|
|||
Loading…
Reference in New Issue