github.com/hugorut/terraform@v1.1.3/website/docs/language/resources/provisioners/connection.mdx (about)

     1  ---
     2  page_title: Provisioner Connection Settings
     3  description: >-
     4    The connection block allows you to manage provisioner connection defaults for
     5    SSH and WinRM.
     6  ---
     7  
     8  # Provisioner Connection Settings
     9  
    10  Most provisioners require access to the remote resource via SSH or WinRM, and
    11  expect a nested `connection` block with details about how to connect.
    12  
    13  -> **Note:** Provisioners should only be used as a last resort. For most
    14  common situations there are better alternatives. For more information, see
    15  [the main Provisioners page](/language/resources/provisioners).
    16  
    17  -> **Note:** In Terraform 0.11 and earlier, providers could set default values
    18  for some connection settings, so that `connection` blocks could sometimes be
    19  omitted. This feature was removed in 0.12 in order to make Terraform's behavior
    20  more predictable.
    21  
    22  -> **Note:** Since the SSH connection type is most often used with
    23  newly-created remote resources, validation of SSH host keys is disabled by
    24  default. In scenarios where this is not acceptable, a separate mechanism for
    25  key distribution could be established and the `host_key` directive documented
    26  below explicitly set to verify against a specific key or signing CA.
    27  
    28  Connection blocks don't take a block label, and can be nested within either a
    29  `resource` or a `provisioner`.
    30  
    31  * A `connection` block nested directly within a `resource` affects all of
    32    that resource's provisioners.
    33  * A `connection` block nested in a `provisioner` block only affects that
    34    provisioner, and overrides any resource-level connection settings.
    35  
    36  One use case for providing multiple connections is to have an initial
    37  provisioner connect as the `root` user to set up user accounts, and have
    38  subsequent provisioners connect as a user with more limited permissions.
    39  
    40  ## Example usage
    41  
    42  ```hcl
    43  # Copies the file as the root user using SSH
    44  provisioner "file" {
    45    source      = "conf/myapp.conf"
    46    destination = "/etc/myapp.conf"
    47  
    48    connection {
    49      type     = "ssh"
    50      user     = "root"
    51      password = "${var.root_password}"
    52      host     = "${var.host}"
    53    }
    54  }
    55  
    56  # Copies the file as the Administrator user using WinRM
    57  provisioner "file" {
    58    source      = "conf/myapp.conf"
    59    destination = "C:/App/myapp.conf"
    60  
    61    connection {
    62      type     = "winrm"
    63      user     = "Administrator"
    64      password = "${var.admin_password}"
    65      host     = "${var.host}"
    66    }
    67  }
    68  ```
    69  
    70  ## The `self` Object
    71  
    72  Expressions in `connection` blocks cannot refer to their parent resource by
    73  name. Instead, they can use the special `self` object.
    74  
    75  The `self` object represents the connection's parent resource, and has all of
    76  that resource's attributes. For example, use `self.public_ip` to reference an
    77  `aws_instance`'s `public_ip` attribute.
    78  
    79  -> **Technical note:** Resource references are restricted here because
    80  references create dependencies. Referring to a resource by name within its own
    81  block would create a dependency cycle.
    82  
    83  ## Argument Reference
    84  
    85  **The following arguments are supported by all connection types:**
    86  
    87  * `type` - The connection type that should be used. Valid types are `ssh` and `winrm`.
    88    Defaults to `ssh`.
    89  
    90  * `user` - The user that we should use for the connection.
    91    Defaults to `root` when using type `ssh` and defaults to `Administrator` when using type `winrm`.
    92  
    93  * `password` - The password we should use for the connection. In some cases this is
    94    specified by the provider.
    95  
    96  * `host` - (Required) The address of the resource to connect to.
    97  
    98  * `port` - The port to connect to.
    99    Defaults to `22` when using type `ssh` and defaults to `5985` when using type `winrm`.
   100  
   101  * `timeout` - The timeout to wait for the connection to become available. Should be provided as a string like `30s` or `5m`.
   102    Defaults to 5 minutes.
   103  
   104  * `script_path` - The path used to copy scripts meant for remote execution.
   105  
   106  **Additional arguments only supported by the `ssh` connection type:**
   107  
   108  * `private_key` - The contents of an SSH key to use for the connection. These can
   109    be loaded from a file on disk using
   110    [the `file` function](/language/functions/file). This takes
   111    preference over the password if provided.
   112  
   113  * `certificate` - The contents of a signed CA Certificate. The certificate argument must be
   114    used in conjunction with a `private_key`. These can
   115    be loaded from a file on disk using the [the `file` function](/language/functions/file).
   116  
   117  * `agent` - Set to `false` to disable using `ssh-agent` to authenticate. On Windows the
   118    only supported SSH authentication agent is
   119    [Pageant](http://the.earth.li/\~sgtatham/putty/0.66/htmldoc/Chapter9.html#pageant).
   120  
   121  * `agent_identity` - The preferred identity from the ssh agent for authentication.
   122  
   123  * `host_key` - The public key from the remote host or the signing CA, used to
   124    verify the connection.
   125  
   126  * `target_platform` - The target platform to connect to. Valid values are `windows` and `unix`. Defaults to `unix` if not set.
   127  
   128    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"`
   129  
   130  **Additional arguments only supported by the `winrm` connection type:**
   131  
   132  * `https` - Set to `true` to connect using HTTPS instead of HTTP.
   133  
   134  * `insecure` - Set to `true` to not validate the HTTPS certificate chain.
   135  
   136  * `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).
   137  
   138  * `cacert` - The CA certificate to validate against.
   139  
   140  <a id="bastion"></a>
   141  
   142  ## Connecting through a Bastion Host with SSH
   143  
   144  The `ssh` connection also supports the following fields to facilitate connnections via a
   145  [bastion host](https://en.wikipedia.org/wiki/Bastion_host).
   146  
   147  * `bastion_host` - Setting this enables the bastion Host connection. This host
   148    will be connected to first, and then the `host` connection will be made from there.
   149  
   150  * `bastion_host_key` - The public key from the remote host or the signing CA,
   151    used to verify the host connection.
   152  
   153  * `bastion_port` - The port to use connect to the bastion host. Defaults to the
   154    value of the `port` field.
   155  
   156  * `bastion_user` - The user for the connection to the bastion host. Defaults to
   157    the value of the `user` field.
   158  
   159  * `bastion_password` - The password we should use for the bastion host.
   160    Defaults to the value of the `password` field.
   161  
   162  * `bastion_private_key` - The contents of an SSH key file to use for the bastion
   163    host. These can be loaded from a file on disk using
   164    [the `file` function](/language/functions/file).
   165    Defaults to the value of the `private_key` field.
   166  
   167  * `bastion_certificate` - The contents of a signed CA Certificate. The certificate argument
   168    must be used in conjunction with a `bastion_private_key`. These can be loaded from
   169    a file on disk using the [the `file` function](/language/functions/file).