|
|
|
|
@ -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"`<br />`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"`<br />`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.
|
|
|
|
|
|
|
|
|
|
<a id="bastion"></a>
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
Laura Pacilio