rock
e800e2cf1c
Three defects, each seen in a live rotation of grafana:
scope the access token needs urn:zitadel:iam:org:project:id:zitadel:aud,
otherwise the management API answers 401 Token.Invalid even though the
assertion was accepted.
app id the objects carry the client id, and the secret endpoint takes the app
resource id. They differ, so every call answered 404 Application
doesn't exist. The correct ids are recorded per object.
attempt time record ActiveCredentialID and LastRotation right after Prepare. Without
it a later failure leaves LastRotation empty, the due check says rotate
now, and each reconcile mints a new secret and restarts the consumer:
grafana was rolled continuously and never became ready.
Also raise the consumer-ready budget to 8 minutes, because grafana needs about four,
and retry a failed attempt after 2 minutes instead of waiting a whole interval.
Credential rotation
One KeyRotation object describes one credential. The controller creates the value,
writes the Secret, proves the new value works, then retires the old one.
Why the state order is the safety property
Prepare -> Publish -> Verify -> Retire
Retire runs only for a provider whose old credential still works after the publish
step, and only after Verify passes. A failure before that point leaves the working
credential untouched. The hand-run rotation that broke Grafana did the opposite: it
regenerated the secret and never re-pointed the consumer.
Two strategies, decided by the provider, not by preference
| Provider | Overlap in ZITADEL | Strategy | Retire |
|---|---|---|---|
zitadel-machine-key |
many keys per service user | overlap |
after the new key obtains a token |
zitadel-oidc-client |
one secret per app | atomic |
nothing to retire |
The single master credential
The controller authenticates with one machine key, mounted from Secret
iam/key-rotation-controller. That key is the only credential the cluster cannot
rotate by itself, so it is the only one that stays encrypted in git.
Every other credential is created by the controller, which means the 34 .enc.yaml
files under k8s/argocd/secrets/ are migration debt, not a design. The retirement
target is one root-of-trust file per thing that cannot rotate itself:
| Survives (root of trust) | Why it cannot rotate |
|---|---|
| ZITADEL instance masterkey | encrypts the whole ZITADEL database |
| Vault unseal keys | unsealing needs a human-held key |
| Talos repair config | recovery path, must work when the cluster does not |
| homelab CA | signs the wildcard certificate |
| controller bootstrap key | chicken and egg: it creates every other key |
| etcd defrag credentials | needed by a job that runs outside the controller |
Everything else — Grafana, Argo CD, Forgejo, MinIO, Paperless, Immich, ComfyUI, api-gw, Gotify — is a KeyRotation object, and its secret leaves git.
Status
The CRD is installed. Eight KeyRotation objects exist for the consumers above and
all are suspend: true: the controller image does not exist yet, so no process acts
on them. poimen-memory is excluded from this migration on purpose.