docs(user): key rotation and retirement runbook
Implements plan step 9 of docs/plans/2026-08-03-s04b-rotation-tooling.md: the operator runbook for encryption key rotation and retirement, per the spec's Runbooks section.
docs/user/key-rotation.md walks the three procedures with
copy-pasteable invocations verified against the implemented flag
surfaces: root key re-encryption (including the S04-A two-edit Vault
promotion ordering and --active-key-uri provenance), two-phase
namespace rotation (rotate, TTL wait, sweep-until-both-counts-zero),
and key-version retirement (the backup-retention-window obligation and
the pre-flight age line). The Kubernetes Job recipe copies the serving
workload's pod template — the platform injects runtime dependencies
(the LabKit infrastructure config, the image override and pull secret)
that this repository's manifests alone do not carry — with an
illustrative manifest labeled as the repo-visible minimum. The failure
triage table covers every operator-facing refusal in the spec's Error
Cases table plus four code-grounded rows (interrupted verification,
lock-contention deadline, barrier stalls, the shredded-namespace
pre-flight transcript). Every quoted message fragment is verbatim from
the source.
Stacking
Targets !1416 (merged)'s branch (sahmed/s04b-step8-namespace-scope); the step 9
changes are the three documentation files on top of it. The page also
documents the retire-key-version action, which lands with !1413 (merged) — this
MR merges after both. Retarget as parents land.
Changes beyond the plan's Step 9 file list
docs/README.md gains the docs/user/ row in its Structure table:
this MR creates the directory's first page, and the docs index lists
every directory.
E2E scenario catalogs
Documentation-only; no scenario affected.
Related to https://gitlab.com/gitlab-org/ops/artifact-registry/-/issues/496