External Vault Requirements for Terraform Enterprise

Terraform Enterprise automatically creates an internally-managed Vault server that stores its data in the PostgreSQL Database. We strongly recommend that organizations use this internally-managed Vault server. However, some organizations have specific requirements around data encryption and auditing. Those organizations can configure Terraform Enterprise to use an external Vault server rather than the internally-managed Vault server.

We only recommend using external Vault when you have experience managing Vault in production. This approach requires that you assume full responsibility for the Vault server, including sealing, unsealing, replication, etc.

Warning: Do not configure multiple Terraform Enterprise instances to use the same namespace on an external Vault server unless they are part of an Active/Active installation. Doing so will result in data loss.

External Vault Configuration

Important: You must configure External Vault during initial installation. After installation, you can only change the configuration using the backup and restore API.

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 extern_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 extern_vault_secret_id Terraform Enterprise configuration setting.

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