» Using SSH Keys for Cloning Modules

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

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

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

» Adding and Deleting Keys

To add or delete an SSH private key, use the main menu to go to your organization's settings and choose "Manage SSH Keys" from the navigation sidebar. This page has a form for adding new keys and a list of existing keys.

TFE screenshot: the manage SSH keys page

To add a key:

  1. Obtain an SSH keypair that TFE 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 won't be able to prompt for it.

    The exact command to create a keypair depends on your OS, but is usually something like ssh-keygen -t rsa -f "/Users/<NAME>/.ssh/service_tfe" -C "service_terraform_enterprise". This creates a service_tfe file with the private key, and a service_tfe.pub file with the public key.

  2. Enter a name for the key in the "Name" field. Choose something identifiable, since the name is the only way to tell two SSH keys apart once the key text is hidden.

  3. Paste the text of the private key in the "Private SSH Key" field.

  4. Click the "Add Private SSH Key" button.

After the key is saved, it will appear below in the list of keys. Keys are only listed by name; TFE retains the text of the private key, but will never again display it for any purpose.

To delete a key, find it in the list of keys and click its "Delete" button. Before deleting a key, you should assign a new key to any workspaces that are using it.

» Assigning Keys to Workspaces

To assign a key to a workspace, navigate to that workspace's page and click the "Integrations" link.

TFE screenshot: the integrations link on a workspace's page

Scroll down and locate the "SSH Key" dropdown menu. Select a named key from the list in this dropdown, then click the "Update VCS Settings" button at the bottom of the page.

TFE screenshot: the SSH key dropdown menu

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