Kubernetes Operator series 2 — Overview of controller-runtime

Masato Naka
3 min readApr 15, 2023


Last time we created a simple example controller with controller-runtime. If you haven’t read the last post, you can read it from here.

In this post, Let’s take a look at the components of controller-runtime.


You can see the main components in architecture in kubebuilder. (Kubebuilder internally uses controller-runtime.)


Most of the components are the ones that we saw in the example controller in the previous introduction.

  1. Manager
  2. Controller
  3. Reconciler
  4. Client
  5. Cache
  6. Webhook

Those are the specific components that we’ll cover in the series.

Flow of Kubernetes controller

In addition to the architecture diagram, I also introduce another chart to help understand the flow of controller.

Manager, Builder, and Reconciler are three important components (highlighted in the diagram) to implement a Kubernetes controller with controller-runtime.

  1. Reconciler is a component to implement a core reconciliation logic.
  2. The Reconciler is registered to a Manager, a component to start up the all registered controller with necessary component, such as client.
  3. When registering a Reconciler, we use Builder, with which we can also specify the target resource of the Reconciler. e.g. Pod, Deployment, or your own custom resource, etc.

Additionally, threre are several more components that we don’t directly touch but are internally used:

  1. Controller is started by the Manager, and when starting, it starts Source, a component that watches changes of the target resources and transmit the information to WorkQueue. Controller subscribes to the WorkQueue to get a Kubernetes object, to which the reconciliation logic is applied.
  2. Client is a component that interacts with API server. Client is initialized with a Manager in another component called Cluster. The initialized client is shared among the registered controllers. The client is passed to each Reconciler so it can update Kubernetes objects to complete the reconciliation logic.

This is the simplified version of the whole picture of how a Kubernetes controller with controller-runtime components works.

If you develop a controller without controller-runtime, although the necessary components can be slightly different, the main flow is the same.

From next time, let’s start with one of those components for deeper understanding.


In this post, we’ve seen the overview of controller created with controller-runtime. Now you should have better understanding of the bird’s-eye view of a Kubernetes controller.

Three important components that you directly touch when developing a Kubernetes controller with controller-runtime:

  1. Reconciler
  2. Manager
  3. Builder

Other components that are internally used or that you don’t necessarily modify when developing:

  1. Controller
  2. Source
  3. WorkQueue
  4. Client

From next time, we’ll study each component with some simple codes.

Series Index

  1. Kubernetes Operator series 1 — controller-runtime example controller
  2. Kubernetes Operator series 2 — Overview of controller-runtime
  3. Kubernetes Operator series 3 — controller-runtime component — Manager
  4. Kubernetes Operator series 4 — controller-runtime component — Builder
  5. Kubernetes Operator series 5 — controller-runtime component — Reconciler
  6. Kubernetes Operator series 6 — controller-runtime component — Controller



Masato Naka

An SRE engineer, mainly working on Kubernetes. CKA (Feb 2021). His Interests include Cloud-Native application development, and machine learning.