Vault Auto-Unseal Runbook

Akira primary Vault runs on akira-mgmt-01-staging and stores application secrets. It auto-unseals through a secondary transit Vault on akira-cache-01-staging.

Architecture

• Primary Vault: management hosts, bound to 127.0.0.1:8200.
• Transit Vault: cache_nodes, bound to its inventory hostname on port 8200.
• Transit key: transit/keys/akira-primary-unseal.
• Primary seal stanza: seal "transit" with a restricted periodic token.
• Token renewal: vault-transit-token-renew.timer runs daily on primary.

The transit Vault still uses Shamir unseal. Store its initial keys offline in KeePass and paper backup; do not commit them.

Initial Setup

1. Deploy transit Vault on cache:

   ansible-playbook -i infra/inventory/staging.yml infra/playbooks/deploy_stateful.yml \
     --vault-password-file ~/.akira-vault-pass.txt --tags vault --limit cache_nodes

2. Initialize and configure transit:

   TRANSIT_HOST=akira-cache-01-staging.tail5f9c92.ts.net scripts/setup-vault-transit.sh

3. Back up /opt/vault/init-keys.txt offline, then remove or tightly restrict the server copy after the offline backup is verified.

4. Add the emitted vault_transit_token, vault_transit_addr, vault_transit_key_name and transit CA certificate to the encrypted infra/group_vars/all/vault.yml.

5. Deploy primary Vault:

   ansible-playbook -i infra/inventory/staging.yml infra/playbooks/deploy_management.yml \
     --vault-password-file ~/.akira-vault-pass.txt --tags vault --limit management

Smoke Test

Run after primary deploy:

ssh root@akira-mgmt-01-staging '
  systemctl restart vault
  sleep 3
  VAULT_ADDR=https://127.0.0.1:8200 vault status | grep "Sealed.*false"
'

Expected result: Sealed is false after restart.

Token Renewal And Rotation

The periodic token is renewed daily by:

systemctl status vault-transit-token-renew.timer
systemctl start vault-transit-token-renew.service

For token rotation, rerun scripts/setup-vault-transit.sh, replace vault_transit_token in encrypted vault.yml, deploy management with --tags vault, then restart primary Vault and rerun the smoke test.

Recovery

If transit Vault is reachable but sealed:

1. Unseal transit Vault manually with 3 offline Shamir keys.
2. Restart primary Vault.
3. Confirm vault status reports Sealed false.

If transit Vault is unavailable:

1. Treat primary Vault as unavailable for secret reads after restart.
2. Restore connectivity or recover transit Vault from offline Shamir keys.
3. Restart primary Vault after transit is healthy.

If the transit Vault data is lost, initialize a replacement transit Vault, create a new akira-primary-unseal key and token, update encrypted vault.yml, then deploy primary Vault. Existing primary seal metadata can only be decrypted by a transit key compatible with the one used to seal it, so keep transit data and Shamir backups in the DR set.