aherman
/
terraform
mirror of https://github.com/hashicorp/terraform
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

website: Document behavior of `self` object for provisioners

Browse Source
pull/23003/head
Nick Fagerlund 7 years ago committed by Nick Fagerlund
parent 39e609d5fd
commit f6e648cc8b
5 changed files with 115 additions and 52 deletions
Show Stats Download Patch File Download Diff File

32
website/docs/configuration/expressions.html.md
Unescape View File

@ -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,

8
website/docs/configuration/resources.html.md
Unescape View File

@ -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

52
website/docs/provisioners/connection.html.markdown
Unescape View File

@ -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.

29
website/docs/provisioners/index.html.markdown
Unescape View File

@ -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:

46
website/layouts/docs.erb
Unescape View File

@ -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>
<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-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-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-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-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-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<%= sidebar_current("docs-provisioners-salt-masterless") %>>
<a href="/docs/provisioners/salt-masterless.html">salt-masterless Provisioner</a>
</li>
</ul>
</li>
</ul>
</li>

Write Preview
Loading…
Cancel
Save