boma/docs/runbooks/rotate-secrets.md

Runbook — Rotating vault secrets

Rotating a single secret value

1. Decrypt the relevant vault file:

   make decrypt FILE=inventories/production/group_vars/all/vault.yml
   

2. Edit the file and update the secret value.

3. Re-encrypt:

   make encrypt FILE=inventories/production/group_vars/all/vault.yml
   

4. Commit the updated vault file:

   git add inventories/production/group_vars/all/vault.yml
   git commit -m "Rotate <secret name>"
   

5. Deploy to apply the new secret to hosts:

   make check PLAYBOOK=site   # verify what will change
   make deploy PLAYBOOK=site
   

---

Rotating the vault password

This affects all encrypted files in the repo. Do this only when:

• A person with vault access leaves the project
• The password is suspected to be compromised

Steps:

1. Ensure you have the current vault password in .vault_pass.

2. Re-key all vault files:

   find . -name "vault.yml" | xargs ansible-vault rekey \
     --vault-password-file .vault_pass \
     --new-vault-password-file /path/to/new_password_file
   

3. Replace .vault_pass with the new password file.

4. Distribute the new password to all collaborators via a secure channel.

5. Commit all rekeyed vault files:

   git add -A
   git commit -m "Rekey all vault files"
   

---

Adding a new collaborator

1. Share the vault password via a secure channel (password manager, etc.)
2. The collaborator creates .vault_pass locally (gitignored)
3. They can now decrypt/encrypt vault files normally

Removing a collaborator's access

Rotate the vault password as described above. There is no per-user access control in Ansible Vault — access is binary (has the password or not).

If per-user access control becomes necessary, evaluate SOPS + age at that point.