← Todos os modelos

Loops de reconciliação idempotentes, status honesto, CRDs versionadas.

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.

  1. Idempotent reconcile loops. Reconcile reads 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.

  2. 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.

  3. Honest status. Status reports what was observed, not what was requested: observedGeneration and standard conditions (Ready, Progressing, Degraded) with reasons and messages. Status is written only through the status subresource.

  4. 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.

  5. 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.

  6. Least-privilege RBAC. The +kubebuilder:rbac markers 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.

  7. 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.