Kubernetes Operator Patterns

Use these patterns to keep controller code Kubernetes-native instead of drifting into ad hoc orchestration.

The operator relies on predictable reconcile loops, explicit controller boundaries, and safe interaction with the API server. These patterns are the default shape of controller work in this repository, especially when app-layer orchestration and manager boundaries are involved.

Diagram

Level-triggered reconciliation

Controllers reconcile the current world against desired state. They do not assume a single event arrives only once.

Decision matrix

Controller patterns to keep

Controller patterns to keep.

Pattern	What it means	Why it matters
Level-triggered reconciliation	Always reconcile from current observed state rather than assuming a single edge event is authoritative.	Controllers may run repeatedly for the same change and still need to converge safely.
Idempotent fetch-check-act flow	Fetch existing state, compare with desired state, and act only when drift exists.	Blind create or blind update paths become noisy and brittle on the second reconcile.
Controller boundary stays thin	Controllers should observe, delegate, patch status, and requeue, not encode deep orchestration directly.	This keeps the app layer and manager boundaries testable and enforceable.
No unmanaged concurrency	Use the context and lifecycle controller-runtime already provides.	Background goroutines lose error handling, ordering, and shutdown semantics.
Structured logging with context	Attach stable keys such as cluster namespace, name, and phase to log entries.	Logs stay queryable and preserve reconcile context across the workflow.

Boundary rules are policy-enforced

Architecture boundaries are generated from .ast-grep/policy/architecture-boundaries.yml and enforced in CI. If a new controller or internal package boundary is required, change the policy first and regenerate the rules in the same branch.

// Controller path: observe, delegate, then return result and error.
result, err := appopenbaocluster.ReconcileAdminOps(ctx, r.Client, req, log, deps)
if err != nil {
    return ctrl.Result{}, err
}
return result, nil

Related implementation guides

ArchitectureUse the architecture section when the next question is which manager or controller owns a responsibility.Go style guideReturn to the language-level rules for naming, errors, and imports.Error handlingOpen the error-specific guidance when the reconcile path needs clearer failure contracts.