diff --git a/website/docs/configuration/expressions.html.md b/website/docs/configuration/expressions.html.md index a7d5d9f26..7dfd45487 100644 --- a/website/docs/configuration/expressions.html.md +++ b/website/docs/configuration/expressions.html.md @@ -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, diff --git a/website/docs/configuration/resources.html.md b/website/docs/configuration/resources.html.md index 18d8da957..e2b337250 100644 --- a/website/docs/configuration/resources.html.md +++ b/website/docs/configuration/resources.html.md @@ -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 diff --git a/website/docs/provisioners/connection.html.markdown b/website/docs/provisioners/connection.html.markdown index e2931d723..7ed6a6a5d 100644 --- a/website/docs/provisioners/connection.html.markdown +++ b/website/docs/provisioners/connection.html.markdown @@ -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. diff --git a/website/docs/provisioners/index.html.markdown b/website/docs/provisioners/index.html.markdown index c3a536ce1..e033a8e12 100644 --- a/website/docs/provisioners/index.html.markdown +++ b/website/docs/provisioners/index.html.markdown @@ -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: diff --git a/website/layouts/docs.erb b/website/layouts/docs.erb index 7b0fb35b8..f1197097f 100644 --- a/website/layouts/docs.erb +++ b/website/layouts/docs.erb @@ -331,33 +331,39 @@ Provisioners Without a Resource - > - chef Provisioner +
  • + Built-in Provisioners +
    • - > - file Provisioner - - - > - habitat Provisioner - - - > - local-exec Provisioner - - - > - puppet Provisioner - - - > - remote-exec Provisioner - - - > - salt-masterless Provisioner -