Vault¶

Vault is the Reemo platform’s secret store: it keeps application credentials (passwords, keys, certificates) encrypted and centralized, and releases them only to authorized services.

Reemo relies on OpenBao, the open-source fork of HashiCorp Vault; the role’s variables and commands keep the term “vault”. This component is optional: it is deployed only with the Credential feature (CREDENTIAL_ENABLED) and the VAULT_ENABLED switch.

What Vault is for¶

Vault is the secret store of the CredentialAPI, the service that manages the credentials of Reemo resources. Secrets are kept in a KV v2 engine, under the secret/ path.

The access chain is as follows:

the API queries the CredentialAPI;
the CredentialAPI reads and writes secrets in Vault, using a dedicated token (credentialapi-admin policy);
isolation is enforced by dynamically created ACL policies (reemo-container-* prefix), a distinct scope per container.

Sealing and unsealing (seal / unseal)¶

For security reasons, Vault never keeps the key that encrypts its data in clear text on disk. At startup it is sealed and cannot read its own secrets: it must be unsealed. This happens on every restart (server reboot, Docker restart, container recreation).

Two unsealing strategies are available:

Manual (Shamir) (default): the master key is split into several shares (5 by default); a threshold of shares (3 by default) is enough to unseal. You can lose up to 2 shares without losing access.
Auto-unseal: Vault unseals automatically through an external service — the Transit engine of another Vault, or AWS KMS.

At initialization (once), the unseal keys and the root token are generated and saved on the Ansible controller (init.json file), to be kept safe.

High availability¶

Vault uses Raft integrated storage:

Raft mode (default): a multi-node cluster, which requires an odd number ≥ 3. Replicas join the leader node and are then unsealed; in 2.6.0, unsealing a freshly joined replica is retried automatically until it is ready.
Single-node fallback: with a single node, the mode automatically falls back to local file storage.

Each replica runs as a dedicated Swarm service, pinned to a node. An HAProxy front provides a stable URL and load-balances across the replicas — Vault is not exposed through Traefik. Communications are protected with TLS/mTLS.