website: Document provisioners
This commit is contained in:
Armon Dadgar
parent
5a178a39a0
commit
93caf16b4c
|
|
@ -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".
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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`.
|
||||
|
||||
|
|
@ -4,52 +4,16 @@
|
|||
<ul class="nav docs-sidenav">
|
||||
<li<%= sidebar_current("docs-home") %>>
|
||||
<a href="/docs/index.html">Documentation Home</a>
|
||||
</li>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-upgrading") %>>
|
||||
<a href="/docs/upgrading.html">Upgrading and Compatibility</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>
|
||||
<li<%= sidebar_current("docs-providers") %>>
|
||||
<a href="/docs/configuration/index.html">Configuration</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>
|
||||
</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>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-agent-running") %>>
|
||||
<a href="/docs/agent/basics.html">Running and Stopping</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-dns") %>>
|
||||
<a href="/docs/agent/dns.html">DNS Interface</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-http") %>>
|
||||
<a href="/docs/agent/http.html">HTTP API</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-config") %>>
|
||||
<a href="/docs/agent/options.html">Configuration</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>
|
||||
<li<%= sidebar_current("docs-providers") %>>
|
||||
<a href="/docs/providers/index.html">Providers</a>
|
||||
<ul class="nav">
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<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-provisioners-file") %>>
|
||||
<a href="/docs/provisioners/file.html">file</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-local") %>>
|
||||
<a href="/docs/provisioners/local-exec.html">local-exec</a>
|
||||
</li>
|
||||
|
||||
<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 %>
|
||||
|
|
|
|||
|
|
@ -4,6 +4,10 @@
|
|||
<ul class="nav docs-sidenav">
|
||||
<li<%= sidebar_current("what") %>>
|
||||
<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") %>>
|
||||
|
|
|
|||
Loading…
Reference in New Issue