rock
c5058dadc6
Two defects that a real rotation exposed:
merge writeSecret replaced the whole Secret map, so every key a consumer
keeps beside the credential disappeared. paperless lost
SOCIALACCOUNT_PROVIDERS_JSON and immich lost config.json; both pods then
failed to start while the rotation reported success.
backoff a Failed attempt returned 0, so the controller retried in a tight loop.
It now waits two minutes and then retries.
All eight objects carry both identifiers ZITADEL needs: the app resource id for the
secret endpoint and the client id for introspection.
Result: seven rotations reach Succeeded with every consumer ready (grafana, comfyui,
argocd, forgejo, paperless, immich, minio). api-gw stays suspended because no workload
exists for it.
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.