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:
- Add
key.v(N+1) alongside key.vN in the <release>-requests-proxy-admin Secret. Leave active: vN.
helm upgrade (or kubectl rollout restart) both deployments → all replicas know v(N) and v(N+1).
- Flip
active: v(N+1). Jobs-manager starts signing with v(N+1). Older live tokens still validate under v(N).
- Wait
tokenTtlSeconds (default 90d) so all v(N)-signed tokens have expired.
- 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.
Context
The stateless-token design (CR-1 / CR-2 / HC-1) bounds leaked-token exposure by the
kidrotation 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.mdcovering the 5-step rotation flow:key.v(N+1)alongsidekey.vNin the<release>-requests-proxy-adminSecret. Leaveactive: vN.helm upgrade(orkubectl rollout restart) both deployments → all replicas know v(N) and v(N+1).active: v(N+1). Jobs-manager starts signing with v(N+1). Older live tokens still validate under v(N).tokenTtlSeconds(default 90d) so all v(N)-signed tokens have expired.key.vN.Operational notes to include in the runbook:
helm.sh/resource-policy: keep, so rotation must edit in place —helm upgrade --reset-valueswould skip the Secret.Link from
README.mdanddocs/MIGRATIONS.md.Acceptance criteria
docs/RUNBOOKS/requests-proxy-key-rotation.md.Dependencies