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">
|
<ul class="nav docs-sidenav">
|
||||||
<li<%= sidebar_current("docs-home") %>>
|
<li<%= sidebar_current("docs-home") %>>
|
||||||
<a href="/docs/index.html">Documentation Home</a>
|
<a href="/docs/index.html">Documentation Home</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
<li<%= sidebar_current("docs-upgrading") %>>
|
<li<%= sidebar_current("docs-providers") %>>
|
||||||
<a href="/docs/upgrading.html">Upgrading and Compatibility</a>
|
<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">
|
<ul class="nav">
|
||||||
<li<%= sidebar_current("docs-internals-architecture") %>>
|
</ul>
|
||||||
<a href="/docs/internals/architecture.html">Architecture</a>
|
</li>
|
||||||
</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") %>>
|
<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">
|
<ul class="nav">
|
||||||
<li<%= sidebar_current("docs-commands-agent") %>>
|
<li<%= sidebar_current("docs-commands-agent") %>>
|
||||||
<a href="/docs/commands/agent.html">agent</a>
|
<a href="/docs/commands/agent.html">agent</a>
|
||||||
|
|
@ -85,45 +49,32 @@
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
<li<%= sidebar_current("docs-agent") %>>
|
<li<%= sidebar_current("docs-providers") %>>
|
||||||
<a href="/docs/agent/basics.html">Terraform Agent</a>
|
<a href="/docs/providers/index.html">Providers</a>
|
||||||
<ul class="nav">
|
<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>
|
|
||||||
</ul>
|
</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") %>>
|
<li<%= sidebar_current("docs-guides") %>>
|
||||||
<a href="/docs/guides/index.html">Guides</a>
|
<a href="/docs/guides/index.html">Guides</a>
|
||||||
|
|
@ -161,6 +112,34 @@
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</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>
|
</ul>
|
||||||
</div>
|
</div>
|
||||||
<% end %>
|
<% end %>
|
||||||
|
|
|
||||||
|
|
@ -4,6 +4,10 @@
|
||||||
<ul class="nav docs-sidenav">
|
<ul class="nav docs-sidenav">
|
||||||
<li<%= sidebar_current("what") %>>
|
<li<%= sidebar_current("what") %>>
|
||||||
<a href="/intro/index.html">What is Terraform?</a>
|
<a href="/intro/index.html">What is Terraform?</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
<li<%= sidebar_current("what") %>>
|
||||||
|
<a href="/intro/index.html">Use Cases</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
<li<%= sidebar_current("vs-other") %>>
|
<li<%= sidebar_current("vs-other") %>>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue