Skip to content

Commit 93caf16

Browse files
armonarmon
committed
website: Document provisioners
1 parent 5a178a3 commit 93caf16

7 files changed

Lines changed: 266 additions & 72 deletions

File tree

‎website/source/docs/provisioners/connection.html.markdown‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
layout: "docs"
3+
page_title: "Provisioner Connections"
4+
sidebar_current: "docs-provisioners-connection"
5+
---
6+
7+
# Provisioner Connections
8+
9+
Many provisioners require access to the remote resource. For example,
10+
a provisioner may need to use ssh to connect to the resource.
11+
12+
Terraform uses a number of defaults when connecting to a resource, but these
13+
can be overriden using `connection` block in either a `resource` or `provisioner`.
14+
Any `connection` information provided in a `resource` will apply to all the
15+
provisioners, but it can be scoped to a single provisioner as well. One use case
16+
is to have an initial provisioner connect as root to setup user accounts, and have
17+
subsequent provisioners connect as a user with more limited permissions.
18+
19+
## Example usage
20+
21+
```
22+
# Copies the file as the root user using a password
23+
provisioner "file" {
24+
source = "conf/myapp.conf"
25+
destination = "/etc/myapp.conf"
26+
connection {
27+
user = "root"
28+
password = "${var.root_password}"
29+
}
30+
}
31+
```
32+
33+
## Argument Reference
34+
35+
The following arugments are supported:
36+
37+
* `type` - The connection type that should be used. This defaults to "ssh". The type
38+
of connection supported depends on the provisioner.
39+
40+
* `user` - The user that we should use for the connection. This defaults to "root".
41+
42+
* `password` - The password we should use for the connection.
43+
44+
* `key_file` - The SSH key to use for the connection. This takes preference over the
45+
password if provided.
46+
47+
* `host` - The address of the resource to connect to. This is provided by the provider.
48+
49+
* `port` - The port to connect to. This defaults to 22.
50+
51+
* `timeout` - The timeout to wait for the conneciton to become available. This defaults
52+
to 5 minutes. Should be provided as a string like "30s" or "5m".
53+

‎website/source/docs/provisioners/file.html.markdown‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
layout: "docs"
3+
page_title: "Provisioner: file"
4+
sidebar_current: "docs-provisioners-file"
5+
---
6+
7+
# File Provisioner
8+
9+
The `file` provisioner is used to copy files or directories from the machine
10+
executing Terraform to the newly created resource. The `file` provisioner only
11+
supports `ssh` type [connections](/docs/provisioners/connection.html).
12+
13+
## Example usage
14+
15+
```
16+
resource "aws_instance" "web" {
17+
...
18+
19+
# Copies the myapp.conf file to /etc/myapp.conf
20+
provisioner "file" {
21+
source = "conf/myapp.conf"
22+
destination = "/etc/myapp.conf"
23+
}
24+
25+
# Copies the configs.d folder to /etc/configs.d
26+
provisioner "file" {
27+
source = "conf/configs.d"
28+
destination = "/etc"
29+
}
30+
}
31+
```
32+
33+
## Argument Reference
34+
35+
The following arugments are supported:
36+
37+
* `source` - (Required) This is the source file or folder. It can be specified as relative
38+
to the current working directory or as an absolute path.
39+
40+
* `destination` - (Required) This is the destination path. It must be specified as an
41+
absolute path.
42+
43+
## Directory Uploads
44+
45+
The file provisioner is also able to upload a complete directory to the remote machine.
46+
When uploading a directory, there are a few important things you should know.
47+
48+
First, the destination directory must already exist. If you need to create it,
49+
use a remote-exec provisioner just prior to the file provisioner in order to create the directory.
50+
51+
Next, the existence of a trailing slash on the source path will determine whether the
52+
directory name will be embedded within the destination, or whether the destination will
53+
be created. An example explains this best:
54+
55+
If the source is `/foo` (no trailing slash), and the destination is `/tmp`, then the contents
56+
of `/foo` on the local machine will be uploaded to `/tmp/foo` on the remote machine. The
57+
`foo` directory on the remote machine will be created by Terraform.
58+
59+
If the source, however, is `/foo/` (a trailing slash is present), and the destination is
60+
`/tmp`, then the contents of `/foo` will be uploaded directly into `/tmp` directly.
61+
62+
This behavior was adopted from the standard behavior of rsync. Note that under the covers,
63+
rsync may or may not be used.
64+

‎website/source/docs/provisioners/index.html.markdown‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
layout: "docs"
3+
page_title: "Provisioners"
4+
sidebar_current: "docs-provisioners"
5+
---
6+
7+
# Provisioners
8+
9+
When a resource is initially created, provisioners can be executed to
10+
initialize that resource. This can be used to add resources to an inventory
11+
management system, run a configuration management tool, bootstrap the
12+
resource into a cluster, etc.
13+
14+
Use the navigation to the left to read about the available provisioners.
15+

‎website/source/docs/provisioners/local-exec.html.markdown‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
layout: "docs"
3+
page_title: "Provisioner: local-exec"
4+
sidebar_current: "docs-provisioners-local"
5+
---
6+
7+
# local-exec Provisioner
8+
9+
The `local-exec` provisioner invokes a local executable after a resource
10+
is created. This invokes a process on the machine running Terraform, not on
11+
the resource. See the `remote-exec` [provisioner](/docs/provisioners/remote-exec.html)
12+
to run commands on the resource.
13+
14+
## Example usage
15+
16+
```
17+
# Join the newly created machine to our Consul cluster
18+
resource "aws_instance" "web" {
19+
...
20+
provisioner "local-exec" {
21+
command = "consul join ${aws_instance.web.private_ip}"
22+
}
23+
}
24+
```
25+
26+
## Argument Reference
27+
28+
The following arugments are supported:
29+
30+
* `command` - (Required) This is the command to execute. It can be provided
31+
as a relative path to the current working directory or as an absolute path.
32+
It is evaluated in a shell, and can use environment variables or Terraform
33+
variables.
34+

‎website/source/docs/provisioners/remote-exec.html.markdown‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
layout: "docs"
3+
page_title: "Provisioner: remote-exec"
4+
sidebar_current: "docs-provisioners-remote"
5+
---
6+
7+
# remote-exec Provisioner
8+
9+
The `remote-exec` provisioner invokes a script on a remote resource after it
10+
is created. This can be used to run a configuration management tool, bootstrap
11+
into a cluster, etc. To invoke a local process, see the `local-exec`
12+
[provisioner](/docs/provisioners/local-exec.html) instead. The `remote-exec`
13+
provisioner only supports `ssh` type [connections](/docs/provisioners/connection.html).
14+
15+
16+
## Example usage
17+
18+
```
19+
# Run puppet and join our Consul cluster
20+
resource "aws_instance" "web" {
21+
...
22+
provisioner "remote-exec" {
23+
inline = [
24+
"puppet apply",
25+
"consul join ${aws_instance.web.private_ip",
26+
]
27+
}
28+
}
29+
```
30+
31+
## Argument Reference
32+
33+
The following arugments are supported:
34+
35+
* `inline` - This is a list of command strings. They are executed in the order
36+
they are provided. This cannot be provided with `script` or `scripts`.
37+
38+
* `script` - This is a path (relative or absolute) to a local script that will
39+
be copied to the remote resource and then executed. This cannot be provided
40+
with `inline` or `scripts`.
41+
42+
* `scripts` - This is a list of paths (relative or absolute) to local scripts
43+
that will be copied to the remote resource and then executed. They are executed
44+
in the order they are provided. This cannot be provided with `inline` or `script`.
45+

‎website/source/layouts/docs.erb‎

Lines changed: 51 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -4,52 +4,16 @@
44
<ul class="nav docs-sidenav">
55
<li<%= sidebar_current("docs-home") %>>
66
<a href="/docs/index.html">Documentation Home</a>
7-
</li>
8-
9-
<li<%= sidebar_current("docs-upgrading") %>>
10-
<a href="/docs/upgrading.html">Upgrading and Compatibility</a>
11-
<ul class="nav">
12-
<li<%= sidebar_current("docs-upgrading-upgrading") %>>
13-
<a href="/docs/upgrading.html">Upgrading Terraform</a>
14-
</li>
15-
16-
<li<%= sidebar_current("docs-upgrading-compat") %>>
17-
<a href="/docs/compatibility.html">Compatibility Promise</a>
18-
</li>
19-
</ul>
20-
</li>
7+
</li>
218

22-
<li<%= sidebar_current("docs-internals") %>>
23-
<a href="/docs/internals/index.html">Terraform Internals</a>
9+
<li<%= sidebar_current("docs-providers") %>>
10+
<a href="/docs/configuration/index.html">Configuration</a>
2411
<ul class="nav">
25-
<li<%= sidebar_current("docs-internals-architecture") %>>
26-
<a href="/docs/internals/architecture.html">Architecture</a>
27-
</li>
28-
29-
<li<%= sidebar_current("docs-internals-consensus") %>>
30-
<a href="/docs/internals/consensus.html">Consensus Protocol</a>
31-
</li>
32-
33-
<li<%= sidebar_current("docs-internals-gossip") %>>
34-
<a href="/docs/internals/gossip.html">Gossip Protocol</a>
35-
</li>
36-
37-
<li<%= sidebar_current("docs-internals-sessions") %>>
38-
<a href="/docs/internals/sessions.html">Sessions</a>
39-
</li>
40-
41-
<li<%= sidebar_current("docs-internals-security") %>>
42-
<a href="/docs/internals/security.html">Security Model</a>
43-
</li>
44-
45-
<li<%= sidebar_current("docs-internals-jepsen") %>>
46-
<a href="/docs/internals/jepsen.html">Jepsen Testing</a>
47-
</li>
48-
</ul>
49-
</li>
12+
</ul>
13+
</li>
5014

5115
<li<%= sidebar_current("docs-commands") %>>
52-
<a href="/docs/commands/index.html">Terraform Commands (CLI)</a>
16+
<a href="/docs/commands/index.html">Commands (CLI)</a>
5317
<ul class="nav">
5418
<li<%= sidebar_current("docs-commands-agent") %>>
5519
<a href="/docs/commands/agent.html">agent</a>
@@ -85,45 +49,32 @@
8549
</ul>
8650
</li>
8751

88-
<li<%= sidebar_current("docs-agent") %>>
89-
<a href="/docs/agent/basics.html">Terraform Agent</a>
90-
<ul class="nav">
91-
<li<%= sidebar_current("docs-agent-running") %>>
92-
<a href="/docs/agent/basics.html">Running and Stopping</a>
93-
</li>
52+
<li<%= sidebar_current("docs-providers") %>>
53+
<a href="/docs/providers/index.html">Providers</a>
54+
<ul class="nav">
55+
</ul>
56+
</li>
9457

95-
<li<%= sidebar_current("docs-agent-dns") %>>
96-
<a href="/docs/agent/dns.html">DNS Interface</a>
58+
<li<%= sidebar_current("docs-provisioners") %>>
59+
<a href="/docs/provisioners/index.html">Provisioners</a>
60+
<ul class="nav">
61+
<li<%= sidebar_current("docs-provisioners-connection") %>>
62+
<a href="/docs/provisioners/connection.html">connection</a>
9763
</li>
9864

99-
<li<%= sidebar_current("docs-agent-http") %>>
100-
<a href="/docs/agent/http.html">HTTP API</a>
101-
</li>
102-
103-
<li<%= sidebar_current("docs-agent-config") %>>
104-
<a href="/docs/agent/options.html">Configuration</a>
65+
<li<%= sidebar_current("docs-provisioners-file") %>>
66+
<a href="/docs/provisioners/file.html">file</a>
10567
</li>
10668

107-
<li<%= sidebar_current("docs-agent-services") %>>
108-
<a href="/docs/agent/services.html">Service Definitions</a>
69+
<li<%= sidebar_current("docs-provisioners-local") %>>
70+
<a href="/docs/provisioners/local-exec.html">local-exec</a>
10971
</li>
11072

111-
<li<%= sidebar_current("docs-agent-checks") %>>
112-
<a href="/docs/agent/checks.html">Check Definitions</a>
113-
</li>
114-
115-
<li<%= sidebar_current("docs-agent-encryption") %>>
116-
<a href="/docs/agent/encryption.html">Encryption</a>
73+
<li<%= sidebar_current("docs-provisioners-remote") %>>
74+
<a href="/docs/provisioners/remote-exec.html">remote-exec</a>
11775
</li>
118-
119-
<li<%= sidebar_current("docs-agent-rpc") %>>
120-
<a href="/docs/agent/rpc.html">RPC Protocol</a>
121-
</li>
122-
123-
<li<%= sidebar_current("docs-agent-telemetry") %>>
124-
<a href="/docs/agent/telemetry.html">Telemetry</a>
125-
</li>
12676
</ul>
77+
</li>
12778

12879
<li<%= sidebar_current("docs-guides") %>>
12980
<a href="/docs/guides/index.html">Guides</a>
@@ -161,6 +112,34 @@
161112
</li>
162113
</ul>
163114

115+
<li<%= sidebar_current("docs-internals") %>>
116+
<a href="/docs/internals/index.html">Internals</a>
117+
<ul class="nav">
118+
<li<%= sidebar_current("docs-internals-architecture") %>>
119+
<a href="/docs/internals/architecture.html">Architecture</a>
120+
</li>
121+
122+
<li<%= sidebar_current("docs-internals-consensus") %>>
123+
<a href="/docs/internals/consensus.html">Consensus Protocol</a>
124+
</li>
125+
126+
<li<%= sidebar_current("docs-internals-gossip") %>>
127+
<a href="/docs/internals/gossip.html">Gossip Protocol</a>
128+
</li>
129+
130+
<li<%= sidebar_current("docs-internals-sessions") %>>
131+
<a href="/docs/internals/sessions.html">Sessions</a>
132+
</li>
133+
134+
<li<%= sidebar_current("docs-internals-security") %>>
135+
<a href="/docs/internals/security.html">Security Model</a>
136+
</li>
137+
138+
<li<%= sidebar_current("docs-internals-jepsen") %>>
139+
<a href="/docs/internals/jepsen.html">Jepsen Testing</a>
140+
</li>
141+
</ul>
142+
</li>
164143
</ul>
165144
</div>
166145
<% end %>

‎website/source/layouts/intro.erb‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44
<ul class="nav docs-sidenav">
55
<li<%= sidebar_current("what") %>>
66
<a href="/intro/index.html">What is Terraform?</a>
7+
</li>
8+
9+
<li<%= sidebar_current("what") %>>
10+
<a href="/intro/index.html">Use Cases</a>
711
</li>
812

913
<li<%= sidebar_current("vs-other") %>>

0 commit comments

Comments
 (0)