ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Language updates

This commit is contained in:
Laura Pacilio 2022-01-05 11:53:39 -05:00 committed by Martin Atkins
parent 5cb8be0d50
commit 63106da0b9
8 changed files with 46 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/docs/language/resources/provisioners/chef.mdx
View File

@ -11,7 +11,7 @@ The `chef` provisioner installs, configures and runs the Chef Client on a remote
resource. The `chef` provisioner supports both `ssh` and `winrm` type resource. The `chef` provisioner supports both `ssh` and `winrm` type
[connections](/language/resources/provisioners/connection). [connections](/language/resources/provisioners/connection).
!> **Warning:** 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. Refer to !> **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 common situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements ## Requirements

135
website/docs/language/resources/provisioners/connection.mdx
View File

@ -7,15 +7,16 @@ description: >-
# Provisioner Connection Settings # 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. 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. There are better alternatives for most common situations. Refer to
common situations there are better alternatives. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Connection Block ## 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 Connection blocks don't take a block label, and can be nested within either a
`resource` or a `provisioner`. `resource` or a `provisioner`.
@ -24,15 +25,9 @@ Connection blocks don't take a block label, and can be nested within either a
* A `connection` block nested in a `provisioner` block only affects that * A `connection` block nested in a `provisioner` block only affects that
provisioner, and overrides any resource-level connection settings. 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.
Since the SSH connection type is most often used with Since the SSH connection type is most often used with
newly-created remote resources, validation of SSH host keys is disabled by newly-created remote resources, validation of SSH host keys is disabled by
default. In scenarios where this is not acceptable, a separate mechanism for 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.
key distribution could be established and the `host_key` directive documented
below explicitly set to verify against a specific key or signing CA.
-> **Note:** In Terraform 0.11 and earlier, providers could set default values -> **Note:** In Terraform 0.11 and earlier, providers could set default values
for some connection settings, so that `connection` blocks could sometimes be for some connection settings, so that `connection` blocks could sometimes be
@ -40,7 +35,7 @@ omitted. This feature was removed in 0.12 in order to make Terraform's behavior
more predictable. more predictable.
## Example usage ### Example usage
```hcl ```hcl
# Copies the file as the root user using SSH # Copies the file as the root user using SSH
@ -79,67 +74,29 @@ 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 that resource's attributes. For example, use `self.public_ip` to reference an
`aws_instance`'s `public_ip` attribute. `aws_instance`'s `public_ip` attribute.
-> **Technical note:** Resource references are restricted here because Resource references are restricted because references create dependencies. Referring to a resource by name within its own block would create a dependency cycle.
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:** | Argument Name | Supported By | Description | Default |
|---------------|--------------|-------------|---------|
* `type` - The connection type that should be used. Valid types are `ssh` and `winrm`. | `type` | Both | The connection type that should be used. Valid types are `"ssh"` and `"winrm"`. | `"ssh"` |
Defaults to `ssh`. | `user` | Both | The user to use for the connection. | `root` for type `"ssh"`<br />`Administrator` for type `"winrm"` |
| `password` | Both | The password we should use for the connection. | |
* `user` - The user that we should use for the connection. | `host` | Both | **Required** - The address of the resource to connect to. | |
Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`. | `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 like `"30s"` or `"5m"`. | `"5m"` |
* `password` - The password we should use for the connection. In some cases this is | `script_path` | Both | 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. | (see below)) |
specified by the provider. | `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). | |
* `host` - (Required) The address of the resource to connect to. | `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. | |
* `port` - The port to connect to. | `host_key` | SSH | The public key from the remote host or the signing CA, used to verify the connection. | |
Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`. | `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. | |
* `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`. | `insecure`| WinRM | Set to `true` to not validate skip validating the HTTPS certificate chain. | |
Defaults to 5 minutes. | `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. For more information, see [Authentication for Remote Connections](https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections) in the Windows App Development documentation. | |
| `cacert` | WinRM | The CA certificate to validate against. | |
* `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 Provisioners typically assume that the remote system runs Microsoft Windows
when using the `winrm` connection type. Behaviors which would vary based on when using the `winrm` connection type. Behaviors which would vary based on
@ -150,32 +107,18 @@ Windows-specific behavior when using WinRM, unless otherwise specified.
## Connecting through a Bastion Host with SSH ## Connecting through a Bastion Host with SSH
The `ssh` connection also supports the following fields to facilitate connnections via a The `ssh` connection also supports the following arguments to connect
[bastion host](https://en.wikipedia.org/wiki/Bastion_host). indirectly via a [bastion host](https://en.wikipedia.org/wiki/Bastion_host).
* `bastion_host` - Setting this enables the bastion Host connection. This host | Argument Name | Description | Default |
will be connected to first, and then the `host` connection will be made from there. |---------------|-------------|---------|
| `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, | `bastion_host_key` | The public key from the remote host or the signing CA, used to verify the host connection. | |
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_port` - The port to use connect to the bastion host. Defaults to the | `bastion_password` | The password to use for the bastion host. | The value of the `password` field. |
value of the `port` 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). |
* `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).
## How Provisioners Execute Remote Scripts ## How Provisioners Execute Remote Scripts
@ -188,7 +131,7 @@ and other context between script statements.
However, this approach does have some consequences which can be relevant in However, this approach does have some consequences which can be relevant in
some unusual situations, even though this is just an implementation detail 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 Most importantly, there must be a suitable location in the remote filesystem
where the provisioner can create the script file. By default, Terraform where the provisioner can create the script file. By default, Terraform
@ -219,7 +162,7 @@ As with the default patterns, provisioners will replace the sequence `%RAND%`
with randomly-selected decimal digits, to reduce the likelihood of collisions with randomly-selected decimal digits, to reduce the likelihood of collisions
between multiple provisioners running concurrently. 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 instead of backslashes, despite the typical convention on Windows, because
the Terraform language uses backslash as the quoted string escape character. the Terraform language uses backslash as the quoted string escape character.

3
website/docs/language/resources/provisioners/file.mdx
View File

@ -12,8 +12,7 @@ The `file` provisioner is used to copy files or directories from the machine
executing Terraform to the newly created resource. The `file` provisioner executing Terraform to the newly created resource. The `file` provisioner
supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection). supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection).
-> **Note:** Provisioners should only be used as a last resort. For most -> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
common situations there are better alternatives. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Example usage ## Example usage

2
website/docs/language/resources/provisioners/habitat.mdx
View File

@ -9,7 +9,7 @@ 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. 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.
!> **Warning:** 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. Refer to !> **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 common situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements ## Requirements

3
website/docs/language/resources/provisioners/null_resource.mdx
View File

@ -19,8 +19,7 @@ details](/language/resources/provisioners/connection) on a `null_resource`. You
use its `triggers` argument and any meta-arguments to control exactly where in use its `triggers` argument and any meta-arguments to control exactly where in
the dependency graph its provisioners will run. the dependency graph its provisioners will run.
-> **Note:** Provisioners should only be used as a last resort. For most -> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
common situations there are better alternatives. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Example usage ## Example usage

2
website/docs/language/resources/provisioners/puppet.mdx
View File

@ -11,7 +11,7 @@ The `puppet` provisioner installs, configures and runs the Puppet agent on a
remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type remote resource. The `puppet` provisioner supports both `ssh` and `winrm` type
[connections](/language/resources/provisioners/connection). [connections](/language/resources/provisioners/connection).
!> **Warning:** 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. Refer to !> **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 common situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements ## Requirements

3
website/docs/language/resources/provisioners/remote-exec.mdx
View File

@ -17,8 +17,7 @@ into a cluster, etc. To invoke a local process, see the `local-exec`
provisioner requires a [connection](/language/resources/provisioners/connection) provisioner requires a [connection](/language/resources/provisioners/connection)
and supports both `ssh` and `winrm`. and supports both `ssh` and `winrm`.
-> **Note:** Provisioners should only be used as a last resort. For most -> **Note:** Provisioners should only be used as a last resort. There are better alternatives for most common situations. Refer to
common situations there are better alternatives. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Example usage ## Example usage

2
website/docs/language/resources/provisioners/salt-masterless.mdx
View File

@ -12,7 +12,7 @@ Type: `salt-masterless`
The `salt-masterless` Terraform provisioner provisions machines built by Terraform 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). using [Salt](http://saltstack.com/) states, without connecting to a Salt master. The `salt-masterless` provisioner supports `ssh` [connections](/language/resources/provisioners/connection).
!> **Warning:** 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. Refer to !> **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 common situations. Refer to
[Declaring Provisioners](/language/resources/provisioners/syntax) for more details. [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
## Requirements ## Requirements