diff --git a/website/data/language-nav-data.json b/website/data/language-nav-data.json index 24100696c..3efdda766 100644 --- a/website/data/language-nav-data.json +++ b/website/data/language-nav-data.json @@ -74,10 +74,6 @@ { "title": "Provisioners", "routes": [ - { - "title": "Overview", - "path": "resources/provisioners" - }, { "title": "Declaring Provisioners", "path": "resources/provisioners/syntax" diff --git a/website/docs/language/resources/index.mdx b/website/docs/language/resources/index.mdx index 08921cf75..79df607b1 100644 --- a/website/docs/language/resources/index.mdx +++ b/website/docs/language/resources/index.mdx @@ -29,7 +29,7 @@ as DNS records. [`provider`](/language/meta-arguments/resource-provider), and [`lifecycle`](/language/meta-arguments/lifecycle). -- [Provisioners](/language/resources/provisioners) +- [Provisioners](/language/resources/provisioners/syntax) documents configuring post-creation actions for a resource using the `provisioner` and `connection` blocks. Since provisioners are non-declarative and potentially unpredictable, we strongly recommend that you treat them as a diff --git a/website/docs/language/resources/provisioners/chef.mdx b/website/docs/language/resources/provisioners/chef.mdx index 9ec4887e2..cf1a2b2a5 100644 --- a/website/docs/language/resources/provisioners/chef.mdx +++ b/website/docs/language/resources/provisioners/chef.mdx @@ -11,7 +11,8 @@ The `chef` provisioner installs, configures and runs the Chef Client on a remote resource. The `chef` provisioner supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection). -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). +!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. ## Requirements diff --git a/website/docs/language/resources/provisioners/connection.mdx b/website/docs/language/resources/provisioners/connection.mdx index eb1ccff5f..987ac7892 100644 --- a/website/docs/language/resources/provisioners/connection.mdx +++ b/website/docs/language/resources/provisioners/connection.mdx @@ -7,37 +7,35 @@ description: >- # Provisioner Connection Settings -Most provisioners require access to the remote resource via SSH or WinRM, and +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](/language/resources/provisioners). +~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. + +## Connection Block + +You can create one or more `connection` blocks that describe how to access the remote resource. One use case for providing multiple connections is to have an initial provisioner connect as the `root` user to set up user accounts and then have subsequent provisioners connect as a user with more limited permissions. + +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. + +Since the SSH connection type is most often used with +newly-created remote resources, validation of SSH host keys is disabled by +default. If this is not acceptable, you can establish a separate mechanism for key distribution and explicitly set the `host_key` argument (details below) to verify against a specific key or signing CA. -> **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. --> **Note:** Since the SSH connection type is most often used with -newly-created remote resources, validation of SSH host keys is disabled by -default. In scenarios where this is not acceptable, a separate mechanism for -key distribution could be established and the `host_key` directive documented -below explicitly set to verify against a specific key or signing CA. -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 +### Example usage ```hcl # Copies the file as the root user using SSH @@ -67,112 +65,53 @@ provisioner "file" { } ``` -## The `self` Object +### The `self` Object -Expressions in `connection` blocks cannot refer to their parent resource by -name. Instead, they can use the special `self` object. +Expressions in `connection` blocks cannot refer to their parent resource by name. References create dependencies, and referring to a resource by name within its own block would create a dependency cycle. Instead, expressions can use the `self` object, which 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. -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 `connection` block supports the following argments. Some arguments are only supported by either the SSH or the WinRM connection type. -**The following arguments are supported by all connection types:** -* `type` - The connection type that should be used. Valid types are `ssh` and `winrm`. - Defaults to `ssh`. +| Argument | Connection Type | Description | Default | +|---------------|--------------|-------------|---------| +| `type` | Both | The connection type. Valid values are `"ssh"` and `"winrm"`. Provisioners typically assume that the remote system runs Microsoft Windows when using WinRM. Behaviors based on the SSH `target_platform` will force Windows-specific behavior for WinRM, unless otherwise specified.| `"ssh"` | +| `user` | Both | The user to use for the connection. | `root` for type `"ssh"`
`Administrator` for type `"winrm"` | +| `password` | Both | The password to use for the connection. | | +| `host` | Both | **Required** - The address of the resource to connect to. | | +| `port` | Both| The port to connect to. | `22` for type `"ssh"`
`5985` for type `"winrm"` | +| `timeout` | Both | The timeout to wait for the connection to become available. Should be provided as a string (e.g., `"30s"` or `"5m"`.) | `"5m"` | +| `script_path` | Both | The path used to copy scripts meant for remote execution. Refer to [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) below for more details. | (details below) | +| `private_key` | SSH | The contents of an SSH key to use for the connection. These can be loaded from a file on disk using [the `file` function](/language/functions/file). This takes preference over `password` if provided. | | +| `certificate` | SSH | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `private_key`. These can be loaded from a file on disk using the [the `file` function](/language/functions/file). | | +| `agent` | SSH | Set to `false` to disable using `ssh-agent` to authenticate. On Windows the only supported SSH authentication agent is [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). | | +| `agent_identity` | SSH | The preferred identity from the ssh agent for authentication. | | +| `host_key` | SSH | The public key from the remote host or the signing CA, used to verify the connection. | | +| `target_platform` | SSH | The target platform to connect to. Valid values are `"windows"` and `"unix"`. If the platform is set to `windows`, the default `script_path` is `c:\windows\temp\terraform_%RAND%.cmd`, assuming [the SSH default shell](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#configuring-the-default-shell-for-openssh-in-windows) is `cmd.exe`. If the SSH default shell is PowerShell, set `script_path` to `"c:/windows/temp/terraform_%RAND%.ps1"` | `"unix"` | +| `https` | WinRM | Set to `true` to connect using HTTPS instead of HTTP. | | +| `insecure` | WinRM | Set to `true` to skip validating the HTTPS certificate chain. | | +| `use_ntlm` | WinRM | Set to `true` to use NTLM authentication rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. Refer to [Authentication for Remote Connections](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections) in the Windows App Development documentation for more details. | | +| `cacert` | WinRM | The CA certificate to validate against. | | -* `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 - specified by the provider. - -* `host` - (Required) The address of the resource 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`. - Defaults to 5 minutes. - -* `script_path` - The path used to copy scripts meant for remote execution. - For more information, see - [How Provisioners Execute Remote Scripts](#how-provisioners-execute-remote-scripts) - below. - -**Additional arguments only supported by the `ssh` connection type:** - -* `private_key` - The contents of an SSH key to use for the connection. These can - be loaded from a file on disk using - [the `file` function](/language/functions/file). This takes - preference over the password if provided. - -* `certificate` - The contents of a signed CA Certificate. The certificate argument must be - used in conjunction with a `private_key`. These can - be loaded from a file on disk using the [the `file` function](/language/functions/file). - -* `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the - only supported SSH authentication agent is - [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant). - -* `agent_identity` - The preferred identity from the ssh agent for authentication. - -* `host_key` - The public key from the remote host or the signing CA, used to - verify the connection. - -* `target_platform` - The target platform to connect to. Valid values are `"windows"` and `"unix"`. Defaults to `"unix"` if not set. - -**Additional arguments only supported by the `winrm` connection type:** - -* `https` - Set to `true` to connect using HTTPS instead of HTTP. - -* `insecure` - Set to `true` to not validate the HTTPS certificate chain. - -* `use_ntlm` - Set to `true` to use NTLM authentication, rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. Further reading for remote connection authentication can be found [here](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections?redirectedfrom=MSDN). - -* `cacert` - The CA certificate to validate against. - -Provisioners typically assume that the remote system runs Microsoft Windows -when using the `winrm` connection type. Behaviors which would vary based on -the `target_platform` option if using SSH will instead force the -Windows-specific behavior when using WinRM, unless otherwise specified. ## Connecting through a Bastion Host with SSH -The `ssh` connection also supports the following fields to facilitate connnections via a -[bastion host](https://en.wikipedia.org/wiki/Bastion_host). +The `ssh` connection also supports the following arguments to connect +indirectly with a [bastion host](https://en.wikipedia.org/wiki/Bastion_host). -* `bastion_host` - Setting this enables the bastion Host connection. This host - will be connected to first, and then the `host` connection will be made from there. - -* `bastion_host_key` - The public key from the remote host or the signing CA, - used to verify the host connection. - -* `bastion_port` - The port to use connect to the bastion host. Defaults to the - value of the `port` field. - -* `bastion_user` - The user for the connection to the bastion host. Defaults to - the value of the `user` field. - -* `bastion_password` - The password we should use for the bastion host. - Defaults to the value of the `password` field. - -* `bastion_private_key` - The contents of an SSH key file to use for the bastion - host. These can be loaded from a file on disk using - [the `file` function](/language/functions/file). - Defaults to the value of the `private_key` field. - -* `bastion_certificate` - The contents of a signed CA Certificate. The certificate argument - must be used in conjunction with a `bastion_private_key`. These can be loaded from - a file on disk using the [the `file` function](/language/functions/file). +| Argument | Description | Default | +|---------------|-------------|---------| +| `bastion_host` | Setting this enables the bastion Host connection. The provisioner will connect to `bastion_host` first, and then connect from there to `host`. | | +| `bastion_host_key` | The public key from the remote host or the signing CA, used to verify the host connection. | | +| `bastion_port` | The port to use connect to the bastion host. | The value of the `port` field.| +| `bastion_user`| The user for the connection to the bastion host. | The value of the `user` field. | +| `bastion_password` | The password to use for the bastion host. | The value of the `password` field. | +| `bastion_private_key` | The contents of an SSH key file to use for the bastion host. These can be loaded from a file on disk using [the `file` function](language/functions/file). | The value of the `private_key` field. | +| `bastion_certificate` | The contents of a signed CA Certificate. The certificate argument must be used in conjunction with a `bastion_private_key`. These can be loaded from a file on disk using the [the `file` function](/language/functions/file). | ## How Provisioners Execute Remote Scripts @@ -185,7 +124,7 @@ and other context between script statements. However, this approach does have some consequences which can be relevant in some unusual situations, even though this is just an implementation detail -for typical use. +in typical use. Most importantly, there must be a suitable location in the remote filesystem where the provisioner can create the script file. By default, Terraform @@ -216,7 +155,7 @@ As with the default patterns, provisioners will replace the sequence `%RAND%` with randomly-selected decimal digits, to reduce the likelihood of collisions between multiple provisioners running concurrently. -If your target system is running Windows, we recommend uses forward slashes +If your target system is running Windows, we recommend using forward slashes instead of backslashes, despite the typical convention on Windows, because the Terraform language uses backslash as the quoted string escape character. @@ -240,7 +179,7 @@ connection { } ``` --> **Warning:** In Terraform v1.0 and earlier, the built-in provisioners +!> **Warning:** In Terraform v1.0 and earlier, the built-in provisioners incorrectly passed the `script_path` value to `scp` through a remote shell and thus allowed it to be subject to arbitrary shell expansion, and thus created an unintended opportunity for remote code execution. Terraform v1.1 and later diff --git a/website/docs/language/resources/provisioners/file.mdx b/website/docs/language/resources/provisioners/file.mdx index 83dfb7a90..8d8b2ac04 100644 --- a/website/docs/language/resources/provisioners/file.mdx +++ b/website/docs/language/resources/provisioners/file.mdx @@ -12,9 +12,8 @@ The `file` provisioner is used to copy files or directories from the machine executing Terraform to the newly created resource. The `file` provisioner supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection). --> **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](/language/resources/provisioners). +~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. ## Example usage diff --git a/website/docs/language/resources/provisioners/habitat.mdx b/website/docs/language/resources/provisioners/habitat.mdx index c8ab535d1..9d5b74774 100644 --- a/website/docs/language/resources/provisioners/habitat.mdx +++ b/website/docs/language/resources/provisioners/habitat.mdx @@ -9,7 +9,8 @@ description: >- The `habitat` provisioner installs the [Habitat](https://habitat.sh) supervisor and loads configured services. This provisioner only supports Linux targets using the `ssh` connection type at this time. -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). +!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. ## Requirements diff --git a/website/docs/language/resources/provisioners/index.mdx b/website/docs/language/resources/provisioners/index.mdx deleted file mode 100644 index badd56b09..000000000 --- a/website/docs/language/resources/provisioners/index.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -page_title: Provisioners Overview - Configuration Language -description: >- - Provisioners model specific actions on a local or remote machine to prepare - servers or other infrastructure for service. ---- - -# Provisioners - -Provisioners can be used to model specific actions on the local machine or on a -remote machine in order to prepare servers or other infrastructure objects for -service. diff --git a/website/docs/language/resources/provisioners/local-exec.mdx b/website/docs/language/resources/provisioners/local-exec.mdx index 02eec0ef7..eda7f9ad0 100644 --- a/website/docs/language/resources/provisioners/local-exec.mdx +++ b/website/docs/language/resources/provisioners/local-exec.mdx @@ -18,9 +18,8 @@ Note that even though the resource will be fully created when the provisioner is run, there is no guarantee that it will be in an operable state - for example system services such as `sshd` may not be started yet on compute resources. --> **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](/language/resources/provisioners). +~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. ## Example usage diff --git a/website/docs/language/resources/provisioners/null_resource.mdx b/website/docs/language/resources/provisioners/null_resource.mdx index 3e7b3fd65..fc270e364 100644 --- a/website/docs/language/resources/provisioners/null_resource.mdx +++ b/website/docs/language/resources/provisioners/null_resource.mdx @@ -19,6 +19,9 @@ details](/language/resources/provisioners/connection) on a `null_resource`. You use its `triggers` argument and any meta-arguments to control exactly where in the dependency graph its provisioners will run. +~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. + ## Example usage ```hcl diff --git a/website/docs/language/resources/provisioners/puppet.mdx b/website/docs/language/resources/provisioners/puppet.mdx index e0894c271..3199caf28 100644 --- a/website/docs/language/resources/provisioners/puppet.mdx +++ b/website/docs/language/resources/provisioners/puppet.mdx @@ -11,7 +11,8 @@ The `puppet` provisioner installs, configures and runs the Puppet agent on a remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection). -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). +!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. ## Requirements diff --git a/website/docs/language/resources/provisioners/remote-exec.mdx b/website/docs/language/resources/provisioners/remote-exec.mdx index 4b4d94274..769ba72de 100644 --- a/website/docs/language/resources/provisioners/remote-exec.mdx +++ b/website/docs/language/resources/provisioners/remote-exec.mdx @@ -17,9 +17,8 @@ into a cluster, etc. To invoke a local process, see the `local-exec` provisioner requires a [connection](/language/resources/provisioners/connection) and supports both `ssh` and `winrm`. --> **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](/language/resources/provisioners). +~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. ## Example usage @@ -27,7 +26,7 @@ common situations there are better alternatives. For more information, see resource "aws_instance" "web" { # ... - # Establishes connection to be used by all + # Establishes connection to be used by all # generic remote provisioners (i.e. file/remote-exec) connection { type = "ssh" diff --git a/website/docs/language/resources/provisioners/salt-masterless.mdx b/website/docs/language/resources/provisioners/salt-masterless.mdx index 70fd17dbe..fbe54fed0 100644 --- a/website/docs/language/resources/provisioners/salt-masterless.mdx +++ b/website/docs/language/resources/provisioners/salt-masterless.mdx @@ -12,7 +12,8 @@ Type: `salt-masterless` The `salt-masterless` Terraform provisioner provisions machines built by Terraform using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/language/resources/provisioners/connection). -!> **Note:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. For most common situations there are better alternatives to using provisioners. For more information, see [the main Provisioners page](/language/resources/provisioners). +!> **Warning:** This provisioner was removed in the 0.15.0 version of Terraform after being deprecated as of Terraform 0.13.4. Provisioners should also be a last resort. There are better alternatives for most situations. Refer to +[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. ## Requirements diff --git a/website/docs/language/resources/syntax.mdx b/website/docs/language/resources/syntax.mdx index 259981bfb..485609ca8 100644 --- a/website/docs/language/resources/syntax.mdx +++ b/website/docs/language/resources/syntax.mdx @@ -129,7 +129,7 @@ The following meta-arguments are documented on separate pages: - [`for_each`, to create multiple instances according to a map, or set of strings](/language/meta-arguments/for_each) - [`provider`, for selecting a non-default provider configuration](/language/meta-arguments/resource-provider) - [`lifecycle`, for lifecycle customizations](/language/meta-arguments/lifecycle) -- [`provisioner` and `connection`, for taking extra actions after resource creation](/language/resources/provisioners) +- [`provisioner`, for taking extra actions after resource creation](/language/resources/provisioners/syntax) ## Operation Timeouts