Passa al contenuto principale

Vault Secret Rotation - Akira

Frequency​

  • API tokens: every 6 months or on suspected compromise.
  • Database passwords: every 12 months.
  • SignalWire PAT: every 12 months.
  • Telegram bot token: every 12 months or on suspected compromise.
  • Sentry DSN: rotate only when project or organization policy requires it.

Canonical files​

  • Vault: infra/group_vars/all/vault.yml.
  • Manifest: infra/group_vars/all/_secrets_manifest.yml.
  • Helper runbook: secret-rotation.md.

General rolling procedure​

Use this pattern for secrets consumed by live services.

  1. Generate the new secret.
  2. Add it to vault with a _new suffix, for example vault_nats_password_new.
  3. Update affected services so both old and new values are accepted.
  4. Cycle services one by one.
  5. Verify all services use the new secret.
  6. Remove the old secret from vault and rename _new to the canonical name.
  7. Update _secrets_manifest.yml with the rotation date.
  8. Update CHANGELOG.md.

Avoid rotating secrets during an active deploy unless the deploy is the mitigation for a security incident.

Check current secret age​

./scripts/check_secrets_age.sh
python3 scripts/check_secrets_age.py

Edit vault​

ansible-vault edit infra/group_vars/all/vault.yml \
  --vault-password-file ~/.akira-vault-pass.txt

Specific secrets​

vault_signalwire_token​

  1. Create a new Personal Access Token in the SignalWire dashboard.

  2. Add vault_signalwire_token_new to the vault.

  3. Re-run signaling deploy for FreeSWITCH.

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

  4. Verify FreeSWITCH package and repository auth still work.

  5. Revoke the old token in SignalWire.

  6. Rename the new vault key to vault_signalwire_token.

vault_postgres_app_password​

  1. Generate a new random password with at least 24 characters.

  2. Add vault_postgres_app_password_new to vault.

  3. Create or alter the app role password during a maintenance window.

    ALTER USER akira_app PASSWORD '<new-password>';

  4. Re-deploy backend and workers.

  5. Verify app, CDR worker, and reports can connect.

  6. Remove the old value from vault after all old connections are drained.

vault_nats_password​

  1. Generate a new password.

  2. Add vault_nats_password_new to vault.

  3. Update NATS config to accept old and new credentials during the rolling window.

  4. Reload NATS.

    docker exec nats nats-server -sl

  5. Re-deploy all clients: CDR worker, Kamailio CDR bridge, backend, and tools.

  6. Verify stream and consumer health.

    nats stream info AKIRA_CDR
    nats consumer info AKIRA_CDR cdr_worker

  7. Remove the old credential.

Telegram bot token​

  1. Create the replacement token through BotFather.
  2. Add vault_telegram_bot_token_new to vault.
  3. Deploy the notification owner service.
  4. Send a test alert to the ops channel.
  5. Revoke the old token.

Sentry DSN​

Sentry DSNs are project-specific identifiers, not passwords. Rotate only when the Sentry project changes or when organization policy requires a new DSN.

Post-rotation smoke test​

ansible-playbook -i infra/inventory/staging.yml \
  infra/playbooks/smoketest.yml \
  --vault-password-file ~/.akira-vault-pass.txt

Completion checklist​

  • New secret verified in service.
  • Old secret revoked or removed.
  • Manifest last_rotation updated.
  • CHANGELOG.md updated.
  • Relevant service owner notified.