# Runbook — Rotating vault secrets

## Rotating a single secret value

1. Decrypt the relevant vault file:
   ```bash
   make decrypt FILE=inventories/production/group_vars/all/vault.yml
   ```

2. Edit the file and update the secret value.

3. Re-encrypt:
   ```bash
   make encrypt FILE=inventories/production/group_vars/all/vault.yml
   ```

4. Commit the updated vault file:
   ```bash
   git add inventories/production/group_vars/all/vault.yml
   git commit -m "Rotate <secret name>"
   ```

5. Deploy to apply the new secret to hosts:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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.