diff --git a/website/.DS_Store b/website/.DS_Store new file mode 100644 index 0000000000..1ace5ab4da Binary files /dev/null and b/website/.DS_Store differ diff --git a/website/source/.DS_Store b/website/source/.DS_Store new file mode 100644 index 0000000000..86e8c58302 Binary files /dev/null and b/website/source/.DS_Store differ diff --git a/website/source/docs/commands/get.html.markdown b/website/source/docs/commands/get.html.markdown new file mode 100644 index 0000000000..80f91b08ee --- /dev/null +++ b/website/source/docs/commands/get.html.markdown @@ -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. diff --git a/website/source/docs/configuration/modules.html.md b/website/source/docs/configuration/modules.html.md new file mode 100644 index 0000000000..07f48ca3cd --- /dev/null +++ b/website/source/docs/configuration/modules.html.md @@ -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 +``` diff --git a/website/source/docs/modules/create.html.markdown b/website/source/docs/modules/create.html.markdown new file mode 100644 index 0000000000..ce0a7f1c4f --- /dev/null +++ b/website/source/docs/modules/create.html.markdown @@ -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. diff --git a/website/source/docs/modules/index.html.markdown b/website/source/docs/modules/index.html.markdown new file mode 100644 index 0000000000..30031ccd33 --- /dev/null +++ b/website/source/docs/modules/index.html.markdown @@ -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. diff --git a/website/source/docs/modules/sources.html.markdown b/website/source/docs/modules/sources.html.markdown new file mode 100644 index 0000000000..fe91eb0286 --- /dev/null +++ b/website/source/docs/modules/sources.html.markdown @@ -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 `` 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. diff --git a/website/source/docs/modules/usage.html.markdown b/website/source/docs/modules/usage.html.markdown new file mode 100644 index 0000000000..9438a5f7bd --- /dev/null +++ b/website/source/docs/modules/usage.html.markdown @@ -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: + +
+ +
+ +But if we set `-module-depth=-1`, the graph will look like this: + +
+ +
+ +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. diff --git a/website/source/images/.DS_Store b/website/source/images/.DS_Store new file mode 100644 index 0000000000..3c795397d8 Binary files /dev/null and b/website/source/images/.DS_Store differ diff --git a/website/source/images/docs/module_graph.png b/website/source/images/docs/module_graph.png new file mode 100644 index 0000000000..196746116f Binary files /dev/null and b/website/source/images/docs/module_graph.png differ diff --git a/website/source/images/docs/module_graph_expand.png b/website/source/images/docs/module_graph_expand.png new file mode 100644 index 0000000000..d9a8631935 Binary files /dev/null and b/website/source/images/docs/module_graph_expand.png differ diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 5880ea849a..3b1c92fe60 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -41,6 +41,10 @@ Outputs + > + Modules + + @@ -51,6 +55,10 @@ apply + > + get + + > graph @@ -131,6 +139,23 @@ + > + Modules + + + > Plugins