kubernetes-sigs/controller-runtime

What it does

controller-runtime is a set of Go libraries for writing Kubernetes controllers. Instead of hand-wiring informers, work queues, and clients, you build on its manager, controller and builder abstractions. It is the runtime layer used by Kubebuilder and Operator SDK, so new projects usually scaffold with one of those and then depend on controller-runtime README.

Typical users are teams writing operators or custom controllers that reconcile Kubernetes resources, and developers who need a stable, versioned client layer tied to Kubernetes releases.

Getting started

New controllers are best started through the Kubebuilder quick start, which generates a project wired to controller-runtime Kubebuilder Quick Start. For direct library use, add the module and follow the package examples:

go get sigs.k8s.io/controller-runtime

Then build a manager and a controller following the documented examples for creating a manager, creating a controller and a basic controller using builder. The examples directory in the repository shows complete programs examples. Running a controller requires access to a Kubernetes cluster and credentials for that cluster; the manager uses the standard kubeconfig or in-cluster configuration.

Version and compatibility constraints

controller-runtime uses a zero major version. Each Kubernetes minor release gets a matching minor version, and breaking changes may appear between minor versions; patch releases do not break compatibility VERSIONING.md. Each minor version is tested against one specific client-go minor version; mixing with other client-go or k8s.io/* minor versions may work but is not supported or tested compatibility table.

The minimum Go version tracks the highest minimum among its Go dependencies, usually matching the corresponding k8s.io/* dependencies. Exact pairs can be read from go.mod go.mod. For example, v0.26 targets k8s.io/* v0.38 and requires Go 1.27.

Contributors must label PRs as bug fixes, backwards-compatible features or breaking changes, and there are templates for each category README.

HotRepo's take

In the Go language daily chart for 5 November 2026, the project recorded 2,984 stars and 1,333 forks with no star change that day, ranking 15th on the Go list. That is a mature base rather than a growth story: its role as the runtime beneath Kubebuilder and Operator SDK is the reason operators depend on it, and the meaningful selection criteria are the Kubernetes and Go version pairing rather than star trends.