IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-01-17 12:12:59 -06:00
Code Issues Packages Projects Releases Wiki Activity
bcc69c05bb
opentofu/website/docs/provisioners/connection.html.markdown
Martin Atkins e0d72930fa website: Warn against using provisioners 
For a long time now we've been advising against the use of provisioners,
but our documentation for them is pretty prominent on the website in
comparision to the better alternatives, and so it's little surprise that
many users end up making significant use of them.

Although in the longer term a change to our information architecture would
probably address this even better, this is an attempt to be explicit about
the downsides of using provisioners and to prominently describe the
alternatives that are available for common use-cases, along with some
reasons why we consider them to be better.

I took the unusual step here of directly linking to specific provider
documentation pages about the alternatives, even though we normally try
to keep the core documentation provider-agnostic, because otherwise that
information tends to be rather buried in the provider documentation and
thus the reader would be reasonable to use provisioners just because we're
not giving specific enough alternative recommendations.
2019-09-05 16:09:06 -07:00

5.4 KiB
Raw Blame History

layout page_title sidebar_current description
docs Provisioner Connections docs-provisioners-connection Managing connection defaults for SSH and WinRM using the `connection` block.

Provisioner Connections

Many provisioners require access to the remote resource. For example, a provisioner may need to use SSH or WinRM to connect to the resource.

-> 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.

Terraform uses a number of defaults when connecting to a resource, but these can be overridden using a connection block in either a resource or provisioner. Any connection information provided in a resource will apply to all the provisioners, but it can be scoped to a single provisioner as well. One use case is to have an initial provisioner connect as the root user to setup user accounts, and have subsequent provisioners connect as a user with more limited permissions.

Example usage

# Copies the file as the root user using SSH
provisioner "file" {
  source      = "conf/myapp.conf"
  destination = "/etc/myapp.conf"

  connection {
    type     = "ssh"
    user     = "root"
    password = "${var.root_password}"
    host     = "${var.host}"
  }
}

# Copies the file as the Administrator user using WinRM
provisioner "file" {
  source      = "conf/myapp.conf"
  destination = "C:/App/myapp.conf"

  connection {
    type     = "winrm"
    user     = "Administrator"
    password = "${var.admin_password}"
    host     = "${var.host}"
  }
}

Argument Reference

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.

  • 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.

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. 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.

  • agent - Set to false to disable using ssh-agent to authenticate. On Windows the only supported SSH authentication agent is 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.

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.

  • cacert - The CA certificate to validate against.

Connecting through a Bastion Host with SSH

The ssh connection also supports the following fields to facilitate connnections via a 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. 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.