diff --git a/website/source/docs/provisioners/connection.html.markdown b/website/source/docs/provisioners/connection.html.markdown new file mode 100644 index 000000000..4206ca990 --- /dev/null +++ b/website/source/docs/provisioners/connection.html.markdown @@ -0,0 +1,53 @@ +--- +layout: "docs" +page_title: "Provisioner Connections" +sidebar_current: "docs-provisioners-connection" +--- + +# Provisioner Connections + +Many provisioners require access to the remote resource. For example, +a provisioner may need to use ssh to connect to the resource. + +Terraform uses a number of defaults when connecting to a resource, but these +can be overriden using `connection` block in either a `resource` or `provisioner`. +Any `connection` information provided in a `resource` will apply to all the +provisioners, but it can be scoped to a single provisioner as well. One use case +is to have an initial provisioner connect as root to setup user accounts, and have +subsequent provisioners connect as a user with more limited permissions. + +## Example usage + +``` +# Copies the file as the root user using a password +provisioner "file" { + source = "conf/myapp.conf" + destination = "/etc/myapp.conf" + connection { + user = "root" + password = "${var.root_password}" + } +} +``` + +## Argument Reference + +The following arugments are supported: + +* `type` - The connection type that should be used. This defaults to "ssh". The type + of connection supported depends on the provisioner. + +* `user` - The user that we should use for the connection. This defaults to "root". + +* `password` - The password we should use for the connection. + +* `key_file` - The SSH key to use for the connection. This takes preference over the + password if provided. + +* `host` - The address of the resource to connect to. This is provided by the provider. + +* `port` - The port to connect to. This defaults to 22. + +* `timeout` - The timeout to wait for the conneciton to become available. This defaults + to 5 minutes. Should be provided as a string like "30s" or "5m". + diff --git a/website/source/docs/provisioners/file.html.markdown b/website/source/docs/provisioners/file.html.markdown new file mode 100644 index 000000000..d3f8457da --- /dev/null +++ b/website/source/docs/provisioners/file.html.markdown @@ -0,0 +1,64 @@ +--- +layout: "docs" +page_title: "Provisioner: file" +sidebar_current: "docs-provisioners-file" +--- + +# File Provisioner + +The `file` provisioner is used to copy files or directories from the machine +executing Terraform to the newly created resource. The `file` provisioner only +supports `ssh` type [connections](/docs/provisioners/connection.html). + +## Example usage + +``` +resource "aws_instance" "web" { + ... + + # Copies the myapp.conf file to /etc/myapp.conf + provisioner "file" { + source = "conf/myapp.conf" + destination = "/etc/myapp.conf" + } + + # Copies the configs.d folder to /etc/configs.d + provisioner "file" { + source = "conf/configs.d" + destination = "/etc" + } +} +``` + +## Argument Reference + +The following arugments are supported: + +* `source` - (Required) This is the source file or folder. It can be specified as relative + to the current working directory or as an absolute path. + +* `destination` - (Required) This is the destination path. It must be specified as an + absolute path. + +## Directory Uploads + +The file provisioner is also able to upload a complete directory to the remote machine. +When uploading a directory, there are a few important things you should know. + +First, the destination directory must already exist. If you need to create it, +use a remote-exec provisioner just prior to the file provisioner in order to create the directory. + +Next, the existence of a trailing slash on the source path will determine whether the +directory name will be embedded within the destination, or whether the destination will +be created. An example explains this best: + +If the source is `/foo` (no trailing slash), and the destination is `/tmp`, then the contents +of `/foo` on the local machine will be uploaded to `/tmp/foo` on the remote machine. The +`foo` directory on the remote machine will be created by Terraform. + +If the source, however, is `/foo/` (a trailing slash is present), and the destination is +`/tmp`, then the contents of `/foo` will be uploaded directly into `/tmp` directly. + +This behavior was adopted from the standard behavior of rsync. Note that under the covers, +rsync may or may not be used. + diff --git a/website/source/docs/provisioners/index.html.markdown b/website/source/docs/provisioners/index.html.markdown new file mode 100644 index 000000000..8fc766a3c --- /dev/null +++ b/website/source/docs/provisioners/index.html.markdown @@ -0,0 +1,15 @@ +--- +layout: "docs" +page_title: "Provisioners" +sidebar_current: "docs-provisioners" +--- + +# Provisioners + +When a resource is initially created, provisioners can be executed to +initialize that resource. This can be used to add resources to an inventory +management system, run a configuration management tool, bootstrap the +resource into a cluster, etc. + +Use the navigation to the left to read about the available provisioners. + diff --git a/website/source/docs/provisioners/local-exec.html.markdown b/website/source/docs/provisioners/local-exec.html.markdown new file mode 100644 index 000000000..5ac15c498 --- /dev/null +++ b/website/source/docs/provisioners/local-exec.html.markdown @@ -0,0 +1,34 @@ +--- +layout: "docs" +page_title: "Provisioner: local-exec" +sidebar_current: "docs-provisioners-local" +--- + +# local-exec Provisioner + +The `local-exec` provisioner invokes a local executable after a resource +is created. This invokes a process on the machine running Terraform, not on +the resource. See the `remote-exec` [provisioner](/docs/provisioners/remote-exec.html) +to run commands on the resource. + +## Example usage + +``` +# Join the newly created machine to our Consul cluster +resource "aws_instance" "web" { + ... + provisioner "local-exec" { + command = "consul join ${aws_instance.web.private_ip}" + } +} +``` + +## Argument Reference + +The following arugments are supported: + +* `command` - (Required) This is the command to execute. It can be provided + as a relative path to the current working directory or as an absolute path. + It is evaluated in a shell, and can use environment variables or Terraform + variables. + diff --git a/website/source/docs/provisioners/remote-exec.html.markdown b/website/source/docs/provisioners/remote-exec.html.markdown new file mode 100644 index 000000000..faf79ab04 --- /dev/null +++ b/website/source/docs/provisioners/remote-exec.html.markdown @@ -0,0 +1,45 @@ +--- +layout: "docs" +page_title: "Provisioner: remote-exec" +sidebar_current: "docs-provisioners-remote" +--- + +# remote-exec Provisioner + +The `remote-exec` provisioner invokes a script on a remote resource after it +is created. This can be used to run a configuration management tool, bootstrap +into a cluster, etc. To invoke a local process, see the `local-exec` +[provisioner](/docs/provisioners/local-exec.html) instead. The `remote-exec` +provisioner only supports `ssh` type [connections](/docs/provisioners/connection.html). + + +## Example usage + +``` +# Run puppet and join our Consul cluster +resource "aws_instance" "web" { + ... + provisioner "remote-exec" { + inline = [ + "puppet apply", + "consul join ${aws_instance.web.private_ip", + ] + } +} +``` + +## Argument Reference + +The following arugments are supported: + +* `inline` - This is a list of command strings. They are executed in the order + they are provided. This cannot be provided with `script` or `scripts`. + +* `script` - This is a path (relative or absolute) to a local script that will + be copied to the remote resource and then executed. This cannot be provided + with `inline` or `scripts`. + +* `scripts` - This is a list of paths (relative or absolute) to local scripts + that will be copied to the remote resource and then executed. They are executed + in the order they are provided. This cannot be provided with `inline` or `script`. + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index c51102838..8f7d96602 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -4,52 +4,16 @@ + > - Terraform Commands (CLI) + Commands (CLI) - > - Terraform Agent - + > + Internals + + <% end %> diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index 41c536ffd..5bc182013 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -4,6 +4,10 @@