Use SSH Keys for cloning modules

Terraform configurations can pull in Terraform modules from a variety of different sources, and private Git repositories are a common source for private modules.

Note: The private module registry is an easier way to manage private Terraform modules in HCP Terraform, and doesn't require setting SSH keys for workspaces. The rest of this page only applies to configurations that fetch modules directly from a private Git repository.

To access a private Git repository, Terraform either needs login credentials (for HTTPS access) or an SSH key. HCP Terraform can store private SSH keys centrally, and you can easily use them in any workspace that clones modules from a Git server.

Note: SSH keys for cloning Terraform modules from Git repos are only used during Terraform runs. They are managed separately from any keys used for bringing VCS content into HCP Terraform.

HCP Terraform manages SSH keys used to clone Terraform modules at the organization level, and allows multiple keys to be added for the organization. You can add or delete keys via the organization's settings. Once a key is uploaded, the text of the key is not displayed to users.

To assign a key to a workspace, go to its settings and choose a previously added key from the drop-down menu on Integrations under "SSH Key". Each workspace can only use one SSH key.

API: See the SSH Keys API and Assign an SSH Key to a Workspace endpoint.
Terraform: See the tfe provider's tfe_ssh_key resource.

Adding Keys

To add a key:

Go to your organization's settings and choose SSH Keys. This page has a form for adding new keys and a list of existing keys.
Obtain a PEM formatted SSH keypair that HCP Terraform can use to download modules during a Terraform run. You might already have an appropriate key. If not, create one on a secure workstation and distribute the public key to your VCS provider(s). Do not use or generate a key that has a passphrase. Git is running non-interactively and cannot prompt for it.
The exact command to create a PEM formatted SSH keypair depends on your operating system. The following example command creates a service_terraform file with the private key and a service_terraform.pub file with the public key.
```
ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise"
```
Enter a name for the key in the Name field. Choose something identifiable. Keys are only listed by name. HCP Terraform retains the text of each private key, but never displays it for any purpose.
Paste the text of the private key in the Private SSH Key field.
Click Add Private SSH Key.

The new key appears in the list of keys on the page.

If you upload an invalid SSH key, upload the correct key and push a new commit for the new key to take effect.

Deleting Keys

Before deleting a key, you should assign a new key to any workspaces that are using it. Otherwise workspaces using the deleted key can no longer clone modules from private repositories. This inability might cause Terraform runs to fail.

To delete a key:

Go to your organization's settings and choose SSH Keys.
Find the key you want to delete and click Delete.

Assigning Keys to Workspaces

To assign a key to a workspace, navigate to that workspace's page and choose "SSH Key" from the "Settings" menu.

Select a named key from the "SSH Key" dropdown menu, then click the "Update SSH key" button.

In subsequent runs, HCP Terraform will use the selected SSH key in this workspace when cloning modules from Git.