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

Edited by Suleimi Ahmed

Merge request reports

Loading
Loading