website: Document behavior of `self` object for provisioners
This commit is contained in:
Nick Fagerlund
Nick Fagerlund
parent
39e609d5fd
commit
f6e648cc8b
|
|
@ -201,6 +201,25 @@ you cannot use square-bracket notation to replace the dot-separated paths, and
|
|||
you cannot iterate over the "parent object" of a named entity (for example, you
|
||||
cannot use `aws_instance` in a `for` expression).
|
||||
|
||||
### Local Named Values
|
||||
|
||||
Within the bodies of certain expressions, or in some other specific contexts,
|
||||
there are other named values available beyond the global values listed above.
|
||||
These local names are described in the documentation for the specific contexts
|
||||
where they appear. Some of most common local names are:
|
||||
|
||||
- `count.index`, in resources that use
|
||||
[the `count` meta-argument](./resources.html#count-multiple-resource-instances-by-count).
|
||||
- `each.key` / `each.value`, in resources that use
|
||||
[the `for_each` meta-argument](./resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings).
|
||||
- `self`, in [provisioner](../provisioners/index.html) and
|
||||
[connection](../provisioners/connection.html) blocks.
|
||||
|
||||
-> **Note:** Local names are often referred to as _variables_ or
|
||||
_temporary variables_ in their documentation. These are not [input
|
||||
variables](./variables.html); they are just arbitrary names
|
||||
that temporarily represent a value.
|
||||
|
||||
### Named Values and Dependencies
|
||||
|
||||
Constructs like resources and module calls often use references to named values
|
||||
|
|
@ -284,19 +303,6 @@ either [splat expressions](#splat-expressions) or index syntax:
|
|||
instances.
|
||||
* `aws_instance.example[0].id` returns just the id of the first instance.
|
||||
|
||||
### Local Named Values
|
||||
|
||||
Within the bodies of certain expressions, or in some other specific contexts,
|
||||
there are other named values available beyond the global values listed above.
|
||||
(For example, the body of a resource block where `count` is set can use a
|
||||
special `count.index` value.) These local names are described in the
|
||||
documentation for the specific contexts where they appear.
|
||||
|
||||
-> **Note:** Local named values are often referred to as _variables_ or
|
||||
_temporary variables_ in their documentation. These are not [input
|
||||
variables](./variables.html); they are just arbitrary names
|
||||
that temporarily represent a value.
|
||||
|
||||
### Values Not Yet Known
|
||||
|
||||
When Terraform is planning a set of changes that will apply your configuration,
|
||||
|
|
|
|||
|
|
@ -274,6 +274,10 @@ identified by an index number, starting with `0`.
|
|||
This is different from resources without `count` or `for_each`, which can be
|
||||
referenced without an index or key.
|
||||
|
||||
-> **Note:** Within nested `provisioner` or `connection` blocks, the special
|
||||
`self` object refers to the current _resource instance,_ not the resource block
|
||||
as a whole.
|
||||
|
||||
#### Using Expressions in `count`
|
||||
|
||||
The `count` meta-argument accepts numeric [expressions](./expressions.html).
|
||||
|
|
@ -370,6 +374,10 @@ identified by a map key (or set member) from the value provided to `for_each`.
|
|||
This is different from resources without `count` or `for_each`, which can be
|
||||
referenced without an index or key.
|
||||
|
||||
-> **Note:** Within nested `provisioner` or `connection` blocks, the special
|
||||
`self` object refers to the current _resource instance,_ not the resource block
|
||||
as a whole.
|
||||
|
||||
#### Using Sets
|
||||
|
||||
The Terraform language doesn't have a literal syntax for
|
||||
|
|
|
|||
|
|
@ -1,27 +1,36 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Provisioner Connections"
|
||||
page_title: "Provisioner Connection Settings"
|
||||
sidebar_current: "docs-provisioners-connection"
|
||||
description: |-
|
||||
Managing connection defaults for SSH and WinRM using the `connection` block.
|
||||
---
|
||||
|
||||
# Provisioner Connections
|
||||
# Provisioner Connection Settings
|
||||
|
||||
Many provisioners require access to the remote resource. For example,
|
||||
a provisioner may need to use SSH or WinRM to connect to the resource.
|
||||
Most provisioners require access to the remote resource via SSH or WinRM, and
|
||||
expect a nested `connection` block with details about how to connect.
|
||||
|
||||
-> **Note:** Provisioners should only be used as a last resort. For most
|
||||
common situations there are better alternatives. For more information, see
|
||||
[the main Provisioners page](./).
|
||||
|
||||
Terraform uses a number of defaults when connecting to a resource, but these can
|
||||
be overridden using a `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 the `root` user to
|
||||
setup user accounts, and have subsequent provisioners connect as a user with
|
||||
more limited permissions.
|
||||
-> **Note:** In Terraform 0.11 and earlier, providers could set default values
|
||||
for some connection settings, so that `connection` blocks could sometimes be
|
||||
omitted. This feature was removed in 0.12 in order to make Terraform's behavior
|
||||
more predictable.
|
||||
|
||||
Connection blocks don't take a block label, and can be nested within either a
|
||||
`resource` or a `provisioner`.
|
||||
|
||||
- A `connection` block nested directly within a `resource` affects all of
|
||||
that resource's provisioners.
|
||||
- A `connection` block nested in a `provisioner` block only affects that
|
||||
provisioner, and overrides any resource-level connection settings.
|
||||
|
||||
One use case for providing multiple connections is to have an initial
|
||||
provisioner connect as the `root` user to set up user accounts, and have
|
||||
subsequent provisioners connect as a user with more limited permissions.
|
||||
|
||||
## Example usage
|
||||
|
||||
|
|
@ -53,14 +62,27 @@ provisioner "file" {
|
|||
}
|
||||
```
|
||||
|
||||
## The `self` Object
|
||||
|
||||
Expressions in `connection` blocks cannot refer to their parent resource by
|
||||
name. Instead, they can use the special `self` object.
|
||||
|
||||
The `self` object represents the connection's parent resource, and has all of
|
||||
that resource's attributes. For example, use `self.public_ip` to reference an
|
||||
`aws_instance`'s `public_ip` attribute.
|
||||
|
||||
-> **Technical note:** Resource references are restricted here because
|
||||
references create dependencies. Referring to a resource by name within its own
|
||||
block would create a dependency cycle.
|
||||
|
||||
## Argument Reference
|
||||
|
||||
**The following arguments are supported by all connection types:**
|
||||
|
||||
* `type` - The connection type that should be used. Valid types are `ssh` and `winrm`.
|
||||
* `type` - The connection type that should be used. Valid types are `ssh` and `winrm`.
|
||||
Defaults to `ssh`.
|
||||
|
||||
* `user` - The user that we should use for the connection.
|
||||
* `user` - The user that we should use for the connection.
|
||||
Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`.
|
||||
|
||||
* `password` - The password we should use for the connection. In some cases this is
|
||||
|
|
@ -68,10 +90,10 @@ provisioner "file" {
|
|||
|
||||
* `host` - (Required) The address of the resource to connect to.
|
||||
|
||||
* `port` - The port to connect to.
|
||||
* `port` - The port to connect to.
|
||||
Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`.
|
||||
|
||||
* `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`.
|
||||
* `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`.
|
||||
Defaults to 5 minutes.
|
||||
|
||||
* `script_path` - The path used to copy scripts meant for remote execution.
|
||||
|
|
|
|||
|
|
@ -142,7 +142,7 @@ the sections above.
|
|||
|
||||
If you are certain that provisioners are the best way to solve your problem
|
||||
after considering the advice in the sections above, you can add a
|
||||
`provisioner` block inside the `resource` block for your compute instance.
|
||||
`provisioner` block inside the `resource` block of a compute instance.
|
||||
|
||||
```hcl
|
||||
resource "aws_instance" "web" {
|
||||
|
|
@ -156,9 +156,30 @@ resource "aws_instance" "web" {
|
|||
|
||||
The `local-exec` provisioner requires no other configuration, but most other
|
||||
provisioners must connect to the remote system using SSH or WinRM.
|
||||
You must write [a `connection` block](./connection.html) so that Terraform
|
||||
You must include [a `connection` block](./connection.html) so that Terraform
|
||||
will know how to communicate with the server.
|
||||
|
||||
Terraform includes several built-in provisioners; use the navigation sidebar to
|
||||
view their documentation. You can also install third-party provisioners in
|
||||
[the user plugins directory](../configuration/providers.html#third-party-plugins).
|
||||
|
||||
All provisioners support the `when` and `on_failure` meta-arguments, which
|
||||
are described below (see [Destroy-Time Provisioners](#destroy-time-provisioners)
|
||||
and [Failure Behavior](#failure-behavior)).
|
||||
|
||||
### The `self` Object
|
||||
|
||||
Expressions in `provisioner` blocks cannot refer to their parent resource by
|
||||
name. Instead, they can use the special `self` object.
|
||||
|
||||
The `self` object represents the provisioner's parent resource, and has all of
|
||||
that resource's attributes. For example, use `self.public_ip` to reference an
|
||||
`aws_instance`'s `public_ip` attribute.
|
||||
|
||||
-> **Technical note:** Resource references are restricted here because
|
||||
references create dependencies. Referring to a resource by name within its own
|
||||
block would create a dependency cycle.
|
||||
|
||||
## Creation-Time Provisioners
|
||||
|
||||
By default, provisioners run when the resource they are defined within is
|
||||
|
|
@ -243,12 +264,12 @@ resource "aws_instance" "web" {
|
|||
## Failure Behavior
|
||||
|
||||
By default, provisioners that fail will also cause the Terraform apply
|
||||
itself to error. The `on_failure` setting can be used to change this. The
|
||||
itself to fail. The `on_failure` setting can be used to change this. The
|
||||
allowed values are:
|
||||
|
||||
- `"continue"` - Ignore the error and continue with creation or destruction.
|
||||
|
||||
- `"fail"` - Error (the default behavior). If this is a creation provisioner,
|
||||
- `"fail"` - Raise an error and stop applying (the default behavior). If this is a creation provisioner,
|
||||
taint the resource.
|
||||
|
||||
Example:
|
||||
|
|
|
|||
|
|
@ -331,33 +331,39 @@
|
|||
<a href="/docs/provisioners/null_resource.html">Provisioners Without a Resource</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-chef") %>>
|
||||
<a href="/docs/provisioners/chef.html">chef Provisioner</a>
|
||||
<li>
|
||||
<a href="#">Built-in Provisioners</a>
|
||||
<ul class="nav nav-auto-expand">
|
||||
<li<%= sidebar_current("docs-provisioners-chef") %>>
|
||||
<a href="/docs/provisioners/chef.html">chef Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-file") %>>
|
||||
<a href="/docs/provisioners/file.html">file Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-habitat") %>>
|
||||
<a href="/docs/provisioners/habitat.html">habitat Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-local") %>>
|
||||
<a href="/docs/provisioners/local-exec.html">local-exec Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-puppet") %>>
|
||||
<a href="/docs/provisioners/puppet.html">puppet Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-remote") %>>
|
||||
<a href="/docs/provisioners/remote-exec.html">remote-exec Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-salt-masterless") %>>
|
||||
<a href="/docs/provisioners/salt-masterless.html">salt-masterless Provisioner</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-file") %>>
|
||||
<a href="/docs/provisioners/file.html">file Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-habitat") %>>
|
||||
<a href="/docs/provisioners/habitat.html">habitat Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-local") %>>
|
||||
<a href="/docs/provisioners/local-exec.html">local-exec Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-puppet") %>>
|
||||
<a href="/docs/provisioners/puppet.html">puppet Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-remote") %>>
|
||||
<a href="/docs/provisioners/remote-exec.html">remote-exec Provisioner</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-provisioners-salt-masterless") %>>
|
||||
<a href="/docs/provisioners/salt-masterless.html">salt-masterless Provisioner</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue