controller-runtime — Specification¶

Focus: Precise reference for the Go library sigs.k8s.io/controller-runtime — the foundation under Kubebuilder and the Operator SDK that ships the manager, the client, the cache, the reconciler, and the controller builder used by every modern Kubernetes operator.

Sources: - Package docs: https://pkg.go.dev/sigs.k8s.io/controller-runtime - GitHub: https://github.com/kubernetes-sigs/controller-runtime - Kubebuilder book: https://book.kubebuilder.io - Operator pattern: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/

1. The operator pattern¶

Kubernetes treats every resource as a desired-state declaration. A controller observes the cluster, compares observed state to desired state, and takes action to close the gap — over and over, forever.

A operator is just one or more controllers packaged with the Custom Resource Definitions (CRDs) they reconcile. The reconciliation function must be idempotent: running it twice with the same input must converge to the same state.

2. Top-level packages¶

3. manager.Manager¶

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
    Scheme:                 scheme,
    LeaderElection:         true,
    LeaderElectionID:       "my-operator.example.com",
    Metrics:                metricsserver.Options{BindAddress: ":8080"},
    HealthProbeBindAddress: ":8081",
    Cache:                  cache.Options{DefaultNamespaces: map[string]cache.Config{"app": {}}},
})

The manager owns the cache and shares it across all controllers it runs. Multiple controllers reconciling the same kind reuse one informer.

4. client.Client¶

type Client interface {
    Reader        // Get, List
    Writer        // Create, Delete, Update, Patch, DeleteAllOf
    StatusClient  // Status().Update / Patch
    SubResourceClientConstructor
    Scheme() *runtime.Scheme
    RESTMapper() meta.RESTMapper
}

Update requires the latest resourceVersion (optimistic locking) — a 409 Conflict means the resource changed under you; refetch and retry.

5. reconcile.Reconciler¶

type Reconciler interface {
    Reconcile(context.Context, Request) (Result, error)
}

type Request struct {
    NamespacedName types.NamespacedName
}

type Result struct {
    Requeue      bool          // re-enqueue immediately (with rate-limit backoff)
    RequeueAfter time.Duration // re-enqueue after this delay (no backoff)
}

Return rules:

The Request contains only the namespaced name — not the object. The reconciler must Get the current state at the top of each call.

6. Controller builder¶

err := ctrl.NewControllerManagedBy(mgr).
    Named("widget-controller").
    For(&v1.Widget{}).
    Owns(&appsv1.Deployment{}).
    Watches(&v1.Config{}, handler.EnqueueRequestsFromMapFunc(mapConfig)).
    WithEventFilter(predicate.GenerationChangedPredicate{}).
    WithOptions(controller.Options{MaxConcurrentReconciles: 5}).
    Complete(&WidgetReconciler{Client: mgr.GetClient()})

7. Event sources, handlers, predicates¶

8. controllerutil helpers¶

CreateOrUpdate fetches first; if found, calls mutate with the existing object; if not, calls mutate on an empty one and creates. The mutate callback is the only place to set spec fields.

9. Finalizers — protocol¶

A finalizer string is conventionally domain/name, e.g. widgets.example.com/cleanup.

10. RBAC marker comments¶

// +kubebuilder:rbac:groups=apps.example.com,resources=widgets,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=apps.example.com,resources=widgets/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=apps.example.com,resources=widgets/finalizers,verbs=update
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
func (r *WidgetReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { ... }

Run controller-gen rbac:roleName=manager-role paths="./..." to emit a Role / ClusterRole from these markers.

11. Webhook framework¶

Register through the manager:

err := ctrl.NewWebhookManagedBy(mgr).
    For(&v1.Widget{}).
    WithDefaulter(&WidgetDefaulter{}).
    WithValidator(&WidgetValidator{}).
    Complete()

12. envtest¶

testEnv := &envtest.Environment{
    CRDDirectoryPaths: []string{filepath.Join("..", "config", "crd", "bases")},
}
cfg, err := testEnv.Start()      // boots etcd + kube-apiserver in this process
defer testEnv.Stop()

k8sClient, _ := client.New(cfg, client.Options{Scheme: scheme})

envtest runs a real kube-apiserver and etcd binary (pinned by setup-envtest) on localhost. No scheduler, no kubelet. Behavior matches a real API server for control-plane code paths but pods never run.

13. Default rate limiter¶

workqueue.DefaultControllerRateLimiter()

is two limiters joined by MaxOf:

Items are de-duplicated in the queue: enqueuing the same Request twice while one is still queued collapses to one entry.

14. Metrics endpoints¶

The manager exposes these on the configured Metrics.BindAddress.

15. Non-goals / limitations¶

• controller-runtime does not scaffold CRDs or YAML — that is kubebuilder / operator-sdk.
• It does not validate spec fields beyond OpenAPI; richer logic goes in a webhook.
• The cache is eventually consistent with the API server; immediately after a Create, a Get may miss.
• The cache is per-manager; running two managers on the same cluster doubles the watch load.
• It does not provide a UI or a CLI — operators are control-plane code only.

16. Related references¶

• API reference: https://pkg.go.dev/sigs.k8s.io/controller-runtime
• Architectural overview: https://github.com/kubernetes-sigs/controller-runtime/blob/main/FAQ.md
• client-go informers (the underlying mechanism): https://pkg.go.dev/k8s.io/client-go/informers
• Kubebuilder book: https://book.kubebuilder.io
• Operator SDK: https://sdk.operatorframework.io