Skip to content

docs: quarterly key-rotation runbook for requests-proxy #98

@saadqbal

Description

@saadqbal

Context

The stateless-token design (CR-1 / CR-2 / HC-1) bounds leaked-token exposure by the kid rotation cadence. We agreed on quarterly rotation. This ticket documents the procedure so anyone on the team can run it.

Parent feature: tracebloc/client-runtime#14

Scope

New docs/RUNBOOKS/requests-proxy-key-rotation.md covering the 5-step rotation flow:

  1. Add key.v(N+1) alongside key.vN in the <release>-requests-proxy-admin Secret. Leave active: vN.
  2. helm upgrade (or kubectl rollout restart) both deployments → all replicas know v(N) and v(N+1).
  3. Flip active: v(N+1). Jobs-manager starts signing with v(N+1). Older live tokens still validate under v(N).
  4. Wait tokenTtlSeconds (default 90d) so all v(N)-signed tokens have expired.
  5. Remove key.vN.

Operational notes to include in the runbook:

  • The Secret has helm.sh/resource-policy: keep, so rotation must edit in place — helm upgrade --reset-values would skip the Secret.
  • Schedule the next rotation calendar reminder when finishing the current one.
  • Reference the CR-1 / CR-2 / HC-1 tickets for design background.

Link from README.md and docs/MIGRATIONS.md.

Acceptance criteria

  • Runbook merged at docs/RUNBOOKS/requests-proxy-key-rotation.md.
  • README and MIGRATIONS link to it.
  • Reviewed by at least one engineer who didn't write the original design (sanity-check that the steps are followable cold).

Dependencies

  • Conceptually depends on HC-1 having shipped, but since this is docs-only it can land in parallel.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions