website: Document behavior of `self` object for provisioners
This commit is contained in:
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
|
you cannot iterate over the "parent object" of a named entity (for example, you
|
||||||
cannot use `aws_instance` in a `for` expression).
|
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
|
### Named Values and Dependencies
|
||||||
|
|
||||||
Constructs like resources and module calls often use references to named values
|
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.
|
instances.
|
||||||
* `aws_instance.example[0].id` returns just the id of the first instance.
|
* `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
|
### Values Not Yet Known
|
||||||
|
|
||||||
When Terraform is planning a set of changes that will apply your configuration,
|
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
|
This is different from resources without `count` or `for_each`, which can be
|
||||||
referenced without an index or key.
|
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`
|
#### Using Expressions in `count`
|
||||||
|
|
||||||
The `count` meta-argument accepts numeric [expressions](./expressions.html).
|
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
|
This is different from resources without `count` or `for_each`, which can be
|
||||||
referenced without an index or key.
|
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
|
#### Using Sets
|
||||||
|
|
||||||
The Terraform language doesn't have a literal syntax for
|
The Terraform language doesn't have a literal syntax for
|
||||||
|
|
|
@ -1,27 +1,36 @@
|
||||||
---
|
---
|
||||||
layout: "docs"
|
layout: "docs"
|
||||||
page_title: "Provisioner Connections"
|
page_title: "Provisioner Connection Settings"
|
||||||
sidebar_current: "docs-provisioners-connection"
|
sidebar_current: "docs-provisioners-connection"
|
||||||
description: |-
|
description: |-
|
||||||
Managing connection defaults for SSH and WinRM using the `connection` block.
|
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,
|
Most provisioners require access to the remote resource via SSH or WinRM, and
|
||||||
a provisioner may need to use SSH or WinRM to connect to the resource.
|
expect a nested `connection` block with details about how to connect.
|
||||||
|
|
||||||
-> **Note:** Provisioners should only be used as a last resort. For most
|
-> **Note:** Provisioners should only be used as a last resort. For most
|
||||||
common situations there are better alternatives. For more information, see
|
common situations there are better alternatives. For more information, see
|
||||||
[the main Provisioners page](./).
|
[the main Provisioners page](./).
|
||||||
|
|
||||||
Terraform uses a number of defaults when connecting to a resource, but these can
|
-> **Note:** In Terraform 0.11 and earlier, providers could set default values
|
||||||
be overridden using a `connection` block in either a `resource` or
|
for some connection settings, so that `connection` blocks could sometimes be
|
||||||
`provisioner`. Any `connection` information provided in a `resource` will apply
|
omitted. This feature was removed in 0.12 in order to make Terraform's behavior
|
||||||
to all the provisioners, but it can be scoped to a single provisioner as well.
|
more predictable.
|
||||||
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
|
Connection blocks don't take a block label, and can be nested within either a
|
||||||
more limited permissions.
|
`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
|
## Example usage
|
||||||
|
|
||||||
|
@ -53,6 +62,19 @@ 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
|
## Argument Reference
|
||||||
|
|
||||||
**The following arguments are supported by all connection types:**
|
**The following arguments are supported by all connection types:**
|
||||||
|
|
|
@ -142,7 +142,7 @@ the sections above.
|
||||||
|
|
||||||
If you are certain that provisioners are the best way to solve your problem
|
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
|
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
|
```hcl
|
||||||
resource "aws_instance" "web" {
|
resource "aws_instance" "web" {
|
||||||
|
@ -156,9 +156,30 @@ resource "aws_instance" "web" {
|
||||||
|
|
||||||
The `local-exec` provisioner requires no other configuration, but most other
|
The `local-exec` provisioner requires no other configuration, but most other
|
||||||
provisioners must connect to the remote system using SSH or WinRM.
|
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.
|
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
|
## Creation-Time Provisioners
|
||||||
|
|
||||||
By default, provisioners run when the resource they are defined within is
|
By default, provisioners run when the resource they are defined within is
|
||||||
|
@ -243,12 +264,12 @@ resource "aws_instance" "web" {
|
||||||
## Failure Behavior
|
## Failure Behavior
|
||||||
|
|
||||||
By default, provisioners that fail will also cause the Terraform apply
|
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:
|
allowed values are:
|
||||||
|
|
||||||
- `"continue"` - Ignore the error and continue with creation or destruction.
|
- `"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.
|
taint the resource.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
|
@ -331,6 +331,9 @@
|
||||||
<a href="/docs/provisioners/null_resource.html">Provisioners Without a Resource</a>
|
<a href="/docs/provisioners/null_resource.html">Provisioners Without a Resource</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
|
<li>
|
||||||
|
<a href="#">Built-in Provisioners</a>
|
||||||
|
<ul class="nav nav-auto-expand">
|
||||||
<li<%= sidebar_current("docs-provisioners-chef") %>>
|
<li<%= sidebar_current("docs-provisioners-chef") %>>
|
||||||
<a href="/docs/provisioners/chef.html">chef Provisioner</a>
|
<a href="/docs/provisioners/chef.html">chef Provisioner</a>
|
||||||
</li>
|
</li>
|
||||||
|
@ -361,6 +364,9 @@
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
|
||||||
<li<%= sidebar_current("docs-modules") %>>
|
<li<%= sidebar_current("docs-modules") %>>
|
||||||
<a href="/docs/modules/index.html">Modules</a>
|
<a href="/docs/modules/index.html">Modules</a>
|
||||||
<ul class="nav">
|
<ul class="nav">
|
||||||
|
|
Loading…
Reference in New Issue