Connect to an external Vault server

This topic describes how to configure Terraform Enterprise to connect to an external Vault server.

Introduction

Using an external Vault server may be necessary if your organization is subject to specific data encryption and auditing compliance requirements. The internal Vault server shipped with Terraform Enterprise that is suitable for most cases.

You should only use an external Vault server if you have experience managing Vault in production. You are responsible for all Vault server operations, including sealing, unsealing, and replication.

Do not configure multiple Terraform Enterprise instances to use the same namespace on an external Vault server unless they are part of a Terraform Enterprise deployment in active-active mode because doing so will result in data loss. Refer to Configure the operational mode for additional information about operational modes.

Complete the following steps to connect to Terraform Enterprise to an external Vault server:

Configure the Vault server: You must enable settings and create policies that allow Terraform Enterprise to connect to Vault.
Specify the Vault settings in the Terraform Enterprise configuration: Refer to the deployment overview for additional information about configuring Terraform Enterprise.

Requirements

You must configure the settings for your external Vault connection before the initial Terraform Enterprise installation. You can only change the configuration after installing Terraform Enterprise using the backup and restore API.

The requirements for deploying Terraform Enterprise depend on the version you want to deploy, as well as the environment you plan to operate the software in, such as operating system, runtime, and storage systems. Check the software product compatibility report page for details.

Configure the Vault server

Run the following commands to configure your external Vault server for use with Terraform Enterprise.

Enable the AppRole Auth Method.

vault auth enable approle

Enable the Transit Secrets Engine.

vault secrets enable transit

Create the tfe-policy.hcl file with the following content:

# To renew leases.
path "sys/leases/renew" {
  capabilities = ["create", "update"]
}
path "sys/renew" {
  capabilities = ["create", "update"]
}

# To renew tokens.
path "auth/token/renew" {
  capabilities = ["create", "update"]
}
path "auth/token/renew-self" {
  capabilities = ["create", "update"]
}

# To perform a login.
path "auth/approle/login" {
  capabilities = ["create", "update"]
}

# To upsert transit keys used for key generation.
path "transit/keys/atlas_*" {
 capabilities = ["read", "create", "update"]
}
path "transit/keys/archivist_*" {
  capabilities = ["read", "create", "update"]
}

# To allow for signing using transit keys
path "transit/sign/atlas_*" {
  capabilities = ["create", "update"]
}

# Encryption and decryption of data.
path "transit/encrypt/atlas_*" {
  capabilities = ["create", "update"]
}
path "transit/decrypt/atlas_*" {
  capabilities = ["create", "update"]
}
path "transit/encrypt/archivist_*" {
  capabilities = ["create", "update"]
}
path "transit/decrypt/archivist_*" {
  capabilities = ["create", "update"]
}

# For performing key derivation.
path "transit/datakey/plaintext/archivist_*" {
  capabilities = ["create", "update"]
}

# For backup/restore operations.
path "transit/keys/atlas_*/config" {
  capabilities = ["read", "create", "update"]
}
path "transit/backup/atlas_*" {
  capabilities = ["read"]
}
path "transit/restore/atlas_*" {
  capabilities = ["read", "create", "update"]
}
path "transit/keys/archivist_*/config" {
  capabilities = ["read", "create", "update"]
}
path "transit/backup/archivist_*" {
  capabilities = ["read"]
}
path "transit/restore/archivist_*" {
  capabilities = ["read", "create", "update"]
}

# For health checks to read the mount table.
path "sys/mounts" {
  capabilities = ["read"]
}

Create the tfe policy using the tfe-policy.hcl policy content.

vault policy write tfe tfe-policy.hcl

Create an AppRole with a periodic token using the tfe policy.

vault write auth/approle/role/tfe policies="tfe" token_period=24h

Fetch the RoleID of the AppRole. This maps back to the TFE_VAULT_ROLE_ID Terraform Enterprise configuration setting.

vault read auth/approle/role/tfe/role-id

Fetch the SecretID of the AppRole. This maps back to the TFE_VAULT_SECRET_ID Terraform Enterprise configuration setting.

vault write -f auth/approle/role/tfe/secret-id

Specify Vault settings

Add the following settings to your Terraform Enterprise configuration:

Set TFE_VAULT_USE_EXTERNAL to true
Set TFE_VAULT_ADDRESS to the full URL of your Vault server, including protocol and port (e.g., https://vault.example.com:8200).
Set TFE_VAULT_ROLE_ID to the RoleID from the AppRole configuration above.
Set TFE_VAULT_SECRET_ID to the SecretID from the AppRole configuration above.
Configure any additional settings specific to your implementation. Refer to the Vault settings reference for details.