Skip to content

ADR-0001: Use Kubebuilder + controller-runtime

  • Status: Accepted
  • Date: 2026-06-02

Context

We are building a Kubernetes operator that reconciles custom resources into administrative objects on an existing IBM MQ Queue Manager. We need a runtime that provides the standard operator machinery — informer caches, work queues, leader election, metrics, health probes, admission webhooks, and CRD/RBAC codegen — so we can focus on reconcile logic rather than plumbing.

We surveyed three reference projects:

  • rko — Kubebuilder v4 / controller-runtime operator. Mature, idiomatic, matches our target layout almost exactly.
  • cert-manager — controller-runtime at large scale; confirms the patterns but carries org-scale overhead we don't want.
  • KubeOps — a minimal operator built directly on raw client-go watches, with no reconcile loop, no cache, no leader election, and (in its sample chart) cluster-admin RBAC.

Decision

We will build the operator with Kubebuilder v4 scaffolding on top of controller-runtime, with thin reconcilers and CRD/RBAC/deepcopy generated by controller-gen.

Consequences

  • We get caching, work queues, rate limiting, leader election, metrics, health probes, and webhook scaffolding for free, satisfying several NFRs (reliability, observability) out of the box.
  • Project layout, codegen, and testing (envtest) follow well-trodden conventions, lowering ramp-up cost and matching the rko reference.
  • We accept controller-runtime as a sizeable dependency and follow its release cadence — an acceptable trade for the machinery it provides.

Alternatives considered

  • Raw client-go (KubeOps style): minimal dependencies, but we would reimplement caches, queues, leader election, and probes — exactly the error-prone plumbing controller-runtime already solves. Rejected.
  • Operator SDK (Go): thin layer over the same controller-runtime; adds tooling we don't need. Kubebuilder is the more direct choice.