Stage 3 · Build

Kubernetes Controllers in Go

Controller-runtime Deep Dive

Manager, client, cache, and builder API for production-ready Kubernetes controllers.

8 min readGo for SREBuild

The Manager

The Manager coordinates all controllers and webhooks in a process. It handles shared concerns: API server connections, caches, health checks, leader election, and graceful shutdown.

Gomanager-setup.go

33 linesLn 1, Col 1Go

NewManager creates the manager with connection settings. Scheme maps Go types to Kubernetes API types. The manager blocks on Start until it receives a shutdown signal. SetupSignalHandler creates a context canceled on SIGINT/SIGTERM.

Client API

The client.Client provides a unified interface for reading and writing Kubernetes resources. It automatically handles caching, serialization, and API version negotiation.

Goclient-operations.go

44 linesLn 1, Col 1Go

Get and List use the cache for read performance. Create, Update, and Patch go directly to the API server. MergeFrom creates a patch from the original object — only changed fields are sent.

Cache and Indexes

The cache stores Kubernetes resources in memory. Reads are fast because they hit the local cache, not the API server. You can configure which resources are cached and add custom indexes.

Gocache-configuration.go

28 linesLn 1, Col 1Go

Cache configuration controls what is cached. Namespaces limits cache to specific namespaces. IndexField adds fast lookup paths for commonly queried fields. Indexed queries are O(1) instead of O(n).

Builder API

The builder API provides a fluent interface for configuring controller watches. It chains For, Owns, Watches, and Complete to set up the event pipeline.

Gobuilder-patterns.go

27 linesLn 1, Col 1Go

For() watches the primary resource type. Owns() watches resources owned by the primary — when a child changes, the parent is reconciled. Watches() adds arbitrary resource watches with custom mapping functions.

Leader Election

Leader election ensures only one instance of your controller runs at a time. Multiple replicas compete for a lock, and only the leader processes reconcile events.

Goleader-election-setup.go

8 linesLn 1, Col 1Go

LeaseDuration controls how long the leader holds the lock. RenewDeadline is the timeout for renewing the lock. RetryPeriod is the wait between lock acquisition attempts. If the leader dies, another replica takes over after the lease expires.

Health Probes

The manager exposes health endpoints for Kubernetes probes. These tell Kubernetes whether your controller is ready to receive traffic and whether it is still alive.

Gohealth-probe-registration.go

28 linesLn 1, Col 1Go

healthz checks that the process is alive. readyz checks that the process is ready to serve — including cache synchronization. Use these probes in your Deployment spec for Kubernetes health management.

Always configure health probes

Without health probes, Kubernetes cannot detect when your controller is stuck or degraded. A controller with an unsynced cache will process stale data. The readyz check ensures traffic only reaches healthy instances.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 3 · Build

Kubernetes Controllers in Go

Controller-runtime Deep Dive

Manager, client, cache, and builder API for production-ready Kubernetes controllers.

8 min readGo for SREBuild

The Manager

The Manager coordinates all controllers and webhooks in a process. It handles shared concerns: API server connections, caches, health checks, leader election, and graceful shutdown.

Gomanager-setup.go

33 linesLn 1, Col 1Go

Client API

The client.Client provides a unified interface for reading and writing Kubernetes resources. It automatically handles caching, serialization, and API version negotiation.

Goclient-operations.go

44 linesLn 1, Col 1Go

Get and List use the cache for read performance. Create, Update, and Patch go directly to the API server. MergeFrom creates a patch from the original object — only changed fields are sent.

Cache and Indexes

The cache stores Kubernetes resources in memory. Reads are fast because they hit the local cache, not the API server. You can configure which resources are cached and add custom indexes.

Gocache-configuration.go

28 linesLn 1, Col 1Go

Cache configuration controls what is cached. Namespaces limits cache to specific namespaces. IndexField adds fast lookup paths for commonly queried fields. Indexed queries are O(1) instead of O(n).

Builder API

The builder API provides a fluent interface for configuring controller watches. It chains For, Owns, Watches, and Complete to set up the event pipeline.

Gobuilder-patterns.go

27 linesLn 1, Col 1Go

Leader Election

Leader election ensures only one instance of your controller runs at a time. Multiple replicas compete for a lock, and only the leader processes reconcile events.

Goleader-election-setup.go

8 linesLn 1, Col 1Go

Health Probes

The manager exposes health endpoints for Kubernetes probes. These tell Kubernetes whether your controller is ready to receive traffic and whether it is still alive.

Gohealth-probe-registration.go

28 linesLn 1, Col 1Go

Always configure health probes

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.