github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/provisioners/connection.html.markdown (about)

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