website: Document provisioners

This commit is contained in:
Armon Dadgar 2014-07-23 12:40:15 -04:00
parent 5a178a39a0
commit 93caf16b4c
7 changed files with 274 additions and 80 deletions

View File

@ -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".

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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`.

View File

@ -6,50 +6,14 @@
<a href="/docs/index.html">Documentation Home</a>
</li>
<li<%= sidebar_current("docs-upgrading") %>>
<a href="/docs/upgrading.html">Upgrading and Compatibility</a>
<li<%= sidebar_current("docs-providers") %>>
<a href="/docs/configuration/index.html">Configuration</a>
<ul class="nav">
<li<%= sidebar_current("docs-upgrading-upgrading") %>>
<a href="/docs/upgrading.html">Upgrading Terraform</a>
</li>
<li<%= sidebar_current("docs-upgrading-compat") %>>
<a href="/docs/compatibility.html">Compatibility Promise</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-internals") %>>
<a href="/docs/internals/index.html">Terraform Internals</a>
<ul class="nav">
<li<%= sidebar_current("docs-internals-architecture") %>>
<a href="/docs/internals/architecture.html">Architecture</a>
</li>
<li<%= sidebar_current("docs-internals-consensus") %>>
<a href="/docs/internals/consensus.html">Consensus Protocol</a>
</li>
<li<%= sidebar_current("docs-internals-gossip") %>>
<a href="/docs/internals/gossip.html">Gossip Protocol</a>
</li>
<li<%= sidebar_current("docs-internals-sessions") %>>
<a href="/docs/internals/sessions.html">Sessions</a>
</li>
<li<%= sidebar_current("docs-internals-security") %>>
<a href="/docs/internals/security.html">Security Model</a>
</li>
<li<%= sidebar_current("docs-internals-jepsen") %>>
<a href="/docs/internals/jepsen.html">Jepsen Testing</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands") %>>
<a href="/docs/commands/index.html">Terraform Commands (CLI)</a>
<a href="/docs/commands/index.html">Commands (CLI)</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-agent") %>>
<a href="/docs/commands/agent.html">agent</a>
@ -85,45 +49,32 @@
</ul>
</li>
<li<%= sidebar_current("docs-agent") %>>
<a href="/docs/agent/basics.html">Terraform Agent</a>
<li<%= sidebar_current("docs-providers") %>>
<a href="/docs/providers/index.html">Providers</a>
<ul class="nav">
<li<%= sidebar_current("docs-agent-running") %>>
<a href="/docs/agent/basics.html">Running and Stopping</a>
</ul>
</li>
<li<%= sidebar_current("docs-agent-dns") %>>
<a href="/docs/agent/dns.html">DNS Interface</a>
<li<%= sidebar_current("docs-provisioners") %>>
<a href="/docs/provisioners/index.html">Provisioners</a>
<ul class="nav">
<li<%= sidebar_current("docs-provisioners-connection") %>>
<a href="/docs/provisioners/connection.html">connection</a>
</li>
<li<%= sidebar_current("docs-agent-http") %>>
<a href="/docs/agent/http.html">HTTP API</a>
<li<%= sidebar_current("docs-provisioners-file") %>>
<a href="/docs/provisioners/file.html">file</a>
</li>
<li<%= sidebar_current("docs-agent-config") %>>
<a href="/docs/agent/options.html">Configuration</a>
<li<%= sidebar_current("docs-provisioners-local") %>>
<a href="/docs/provisioners/local-exec.html">local-exec</a>
</li>
<li<%= sidebar_current("docs-agent-services") %>>
<a href="/docs/agent/services.html">Service Definitions</a>
</li>
<li<%= sidebar_current("docs-agent-checks") %>>
<a href="/docs/agent/checks.html">Check Definitions</a>
</li>
<li<%= sidebar_current("docs-agent-encryption") %>>
<a href="/docs/agent/encryption.html">Encryption</a>
</li>
<li<%= sidebar_current("docs-agent-rpc") %>>
<a href="/docs/agent/rpc.html">RPC Protocol</a>
</li>
<li<%= sidebar_current("docs-agent-telemetry") %>>
<a href="/docs/agent/telemetry.html">Telemetry</a>
<li<%= sidebar_current("docs-provisioners-remote") %>>
<a href="/docs/provisioners/remote-exec.html">remote-exec</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-guides") %>>
<a href="/docs/guides/index.html">Guides</a>
@ -161,6 +112,34 @@
</li>
</ul>
<li<%= sidebar_current("docs-internals") %>>
<a href="/docs/internals/index.html">Internals</a>
<ul class="nav">
<li<%= sidebar_current("docs-internals-architecture") %>>
<a href="/docs/internals/architecture.html">Architecture</a>
</li>
<li<%= sidebar_current("docs-internals-consensus") %>>
<a href="/docs/internals/consensus.html">Consensus Protocol</a>
</li>
<li<%= sidebar_current("docs-internals-gossip") %>>
<a href="/docs/internals/gossip.html">Gossip Protocol</a>
</li>
<li<%= sidebar_current("docs-internals-sessions") %>>
<a href="/docs/internals/sessions.html">Sessions</a>
</li>
<li<%= sidebar_current("docs-internals-security") %>>
<a href="/docs/internals/security.html">Security Model</a>
</li>
<li<%= sidebar_current("docs-internals-jepsen") %>>
<a href="/docs/internals/jepsen.html">Jepsen Testing</a>
</li>
</ul>
</li>
</ul>
</div>
<% end %>

View File

@ -6,6 +6,10 @@
<a href="/intro/index.html">What is Terraform?</a>
</li>
<li<%= sidebar_current("what") %>>
<a href="/intro/index.html">Use Cases</a>
</li>
<li<%= sidebar_current("vs-other") %>>
<a href="/intro/vs/index.html">Terraform vs. Other Software</a>
<ul class="nav">