kms.md

KMS Backends

The KMS backend is responsible for encrypting and decrypting the state file, so that the stored data is always encrypted at rest.

Local Key

This backend uses a key defined as an environment variable to encrypt the state files.

A key can be generated by running: ./terraform-backend

Config

Set KMS_BACKEND to local.

Environment Variable	Type	Example	Description
KMS_KEY	string	jwS6UpASMOWpEmFn7C6I47BlmPt4cpdmYLKd2E7a4Zk=	If local KMS is enabled, but no key is defined, the server will generate a new one and exit

Key from Vault Key/Value Secrets Engine

Alternatively the key can be fetched from a HashiCorp Vault Key/Value secrets engine (v2)

Config

Set KMS_BACKEND to vault.

Environment Variable	Type	Example	Description
KMS_VAULT_KEY_PATH	string	kv/data/terraform-backend	Path of the key secret

Make sure that the Vault client is set up properly.

Vault Transit Secrets Engine

HashiCorp Vault Transit secrets engine allows delegating the en-/decryption process to a Vault server, so that even the Terraform backend server doesn't know the key.

For preparing the disaster recovery, the Transit key can be exported and the state files can be converted to use a local key for decryption by using the convert-transit-state.sh script.

Config

Set KMS_BACKEND to transit.

Environment Variable	Type	Example	Description
KMS_TRANSIT_ENGINE	string	transit	Name (mount point) of the Transit secrets engine
KMS_TRANSIT_KEY	string	terraform-backend	Name of the Transit key

Make sure that the Vault client is set up properly.