controller-runtime: The Engine for Kubernetes Operators

Why it exists

Writing a Kubernetes controller from scratch is complex. You need to handle watching API resources, managing a local cache to avoid overwhelming the API server, queuing work items, and ensuring only one controller instance is active (leader election). controller-runtime was created to solve this by providing robust, reusable components for this common logic.

The mental model

controller-runtime is the standard engine block for a custom Kubernetes controller. Instead of building the pistons, crankshaft, and transmission (API watches, caches, work queues) yourself, you get a pre-built engine. You just need to add your specific business logic—the 'car' built around the engine—that defines how to reconcile a specific resource.

How it works

The library provides several key abstractions. A 'Manager' sets up shared components like connections to the API server, caches, and leader election. You then attach one or more 'Controllers' to the Manager. Each Controller specifies which resources to 'Watch' (e.g., Deployments, or a custom resource) and provides a 'Reconcile' function. This function contains your logic and is called whenever a watched object changes. The library handles the event-driven plumbing to trigger your reconcile loop.

When to use it

You use controller-runtime when building custom Kubernetes controllers or operators in Go. It's the de-facto standard and is the underlying library for major tools like Kubebuilder and the Operator SDK. If you need fine-grained control that a higher-level framework doesn't expose, you'll work with its APIs directly.

When not to use it

Don't use it for simple, one-off scripts that interact with the Kubernetes API; a client library like client-go is more appropriate. For most new operator projects, starting with a higher-level framework like Kubebuilder or Operator SDK is recommended, as they provide scaffolding and code generation on top of controller-runtime.

One canonical example

A database operator defines a 'Database' Custom Resource. The controller, built with controller-runtime, watches for these objects. When a user creates a 'Database' object named 'my-prod-db', the reconcile loop is triggered. The loop's logic then creates a corresponding StatefulSet, Service, and Secret to run the actual database, bringing the cluster's state in line with the user's request.