Boucles de réconciliation idempotentes, statut honnête, CRD versionnées.
Constitution — Kubernetes operator
Version 1.0.0 · Ratified 2026-11-10
These principles hold for every spec, plan and task of the operator. A spec may add rules; it never weakens these.
-
Idempotent reconcile loops.
Reconcilereads the current state and moves it toward the desired state, whatever happened before. Running it twice in a row makes no second change, and an envtest case checks exactly that. -
Level-based, not event-based. The reconciler never depends on which event triggered it or on in-memory state from a previous run. Everything it needs is read from the API server or the cache.
-
Honest status. Status reports what was observed, not what was requested:
observedGenerationand standardconditions(Ready,Progressing,Degraded) with reasons and messages. Status is written only through the status subresource. -
Versioned CRDs. CRDs have a served and stored version, OpenAPI validation and CEL rules for invariants. A breaking change adds a new API version with a conversion webhook; fields are never removed from a served version.
-
Owned resources are cleaned up. Child resources carry owner references, and external resources are released through a finalizer that is removed only after the cleanup succeeds. Deleting a custom resource never leaves orphans.
-
Least-privilege RBAC. The
+kubebuilder:rbacmarkers list only the verbs and resources the controller uses, and the generated role is reviewed on every change. The operator never asks for cluster-admin. -
Errors requeue with backoff. Transient errors are returned so controller-runtime retries with backoff; expected waits use
RequeueAfter. The reconciler never sleeps or loops inside one call, and reconcile errors and duration are exported as metrics.