Skip to main content

Rotate a Vault secret without downtime

Phase 6 slice 3 introduced declaragent secrets rotate, which bumps a secret's version and triggers a graceful re-resolve across every active session.

The flow​

  1. Rotate the underlying secret in Vault (out-of-band).
  2. Tell Declaragent to pick up the new version: 
    declaragent secrets rotate secret:slack/bot-token --reason "90-day schedule"
  3. Verify with declaragent secrets describe secret:slack/bot-token — the version field should bump and lastRotatedAt should be fresh.

What happens inside​

Real rotation is provider-owned — Vault (or AWS SM / GCP SM) rotates the value itself. declaragent secrets rotate marks the rotation moment on the Declaragent side; it does not fan anything out to running sessions:

  • The CLI re-resolves the ref to prove the provider + new value are reachable — a failed resolve aborts with ✗ rotate aborted instead of recording a rotation.
  • A secret_access record (requester cli:secrets-rotate) is written to the hash-chained audit log, so the rotation moment is traceable.
  • Live processes pick up the new value when their resolver cache TTL expires or on restart — there is no secret_rotated bus event or live adapter rebind today; restart long-lived daemons (declaragent down && declaragent up -d) to force it.

Tenant scope​

If you run multiple tenants, scope the audit record to the affected tenant:

declaragent secrets rotate secret:slack/bot-token --tenant acme-prod

Without --tenant, the record is written under the default tenant context.

Failure modes​

SymptomCauseFix
EPERMVault token lacks update on the path.Refresh the Declaragent service principal's Vault policy.
Session sees stale value after rotateResolver cache TTL hasn't elapsed (no live fan-out exists).declaragent secrets describe — if Declaragent sees the new version, restart the affected daemon (declaragent down && declaragent up -d).
secret-rotation-overdue alert firesSLO says rotate every N days; you haven't.See runbook.