Vault Backend

A Terraform HTTP backend that stores the state in a Vault secret.

The server supports locking and leverages the versioning capabilities of Vault by creating a new secret version when creating/updating the state.

Terraform config

The server authenticates to Vault using AppRole, with role_id and secret_id passed respectively as the username and password in the configuration:

terraform {
  backend "http" {
    address = "http://localhost:8080/state/<STATE_NAME>"
    lock_address = "http://localhost:8080/state/<STATE_NAME>"
    unlock_address = "http://localhost:8080/state/<STATE_NAME>"

    username = "<VAULT_ROLE_ID>"
    password = "<VAULT_SECRET_ID>"
  }
}

or directly with a token:

terraform {
  backend "http" {
    address = "http://localhost:8080/state/<STATE_NAME>"
    lock_address = "http://localhost:8080/state/<STATE_NAME>"
    unlock_address = "http://localhost:8080/state/<STATE_NAME>"

    username = "TOKEN"
    password = "<TOKEN_VALUE>"
  }
}

where <STATE_NAME> is an arbitrary value used to distinguish the backends.

With the above configuration, Terraform connects to a vault-backend server running locally on port 8080 when loading/storing/locking the state, and the server manages the following secrets in Vault:

• /<VAULT_STORE>/<VAULT_PREFIX>/<STATE_NAME>
• /<VAULT_STORE>/<VAULT_PREFIX>/<STATE_NAME>-lock

the latter gets created when a lock is acquired and deleted when released.

Vault Backend config

The following environment variables can be set to change the configuration:

• VAULT_URL (default http://localhost:8200) the URL of the Vault server
• VAULT_PREFIX (default vbk) the prefix used when storing the secrets
• VAULT_STORE (default secret) the store path used when storing secrets
• LISTEN_ADDRESS (default 0.0.0.0:8080) the listening address and port
• TLS_CRT and TLS_KEY to set the path of the TLS certificate and key files
• DEBUG to enable verbose logging

Vault policy

The policy associated to the AppRole used by the server needs to grant access to the secrets.

I.e., for a <STATE_NAME> set as cloud-services and the default VAULT_PREFIX and VAULT_STORE:

path "secret/data/vbk/cloud-services"
{
  capabilities = ["create", "read", "update"]
}

path "secret/data/vbk/cloud-services-lock"
{
  capabilities = ["create", "read", "update"]
}

path "secret/metadata/vbk/cloud-services-lock"
{
  capabilities = ["delete"]
}

Docker

The Docker images for Vault Backend are available here: https://hub.docker.com/r/gherynos/vault-backend

Example execution command:

docker run -d -p 8080:8080 -e VAULT_URL=https://some.vault.address:8200 gherynos/vault-backend

Author

GitHub @gherynos

License

Vault Backend is licensed under the Apache License, Version 2.0.