controller-runtime Manager, Client & Scheme

Every production Go operator centers on a controller-runtime Manager that shares caches and lifecycle hooks across reconcilers, webhooks, and health endpoints.

The typed Client and Scheme are the two objects reconcilers use on every loop.

Summary

The Manager starts informer caches, exposes GetClient() and GetScheme(), and runs until SIGTERM.

The Client performs Get/List/Create/Update/Patch/Delete against Kubernetes objects, preferring cache reads for watched types.

The Scheme registers your CRD Go types plus core API types so the REST mapper can decode unstructured objects into structs.

Bootstrapping happens once in cmd/main.go; reconcilers receive dependencies via struct fields.

Recipe

Quick-reference recipe card - copy-paste ready.

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
    Scheme: scheme,
    Metrics: metricsserver.Options{BindAddress: ":8080"},
    HealthProbeBindAddress: ":8081",
    LeaderElection:         true,
    LeaderElectionID:       "guestbook.example.com",
})

When to reach for this:

• Starting any kubebuilder or controller-runtime operator
• Sharing one cache across multiple reconcilers in a single process
• Enabling metrics, health probes, and leader election in one place
• Registering admission webhooks on the same HTTP server as metrics

Working Example

package main
 
import (
    "os"
 
    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/runtime"
    utilruntime "k8s.io/apimachinery/pkg/util/runtime"
    clientgoscheme "k8s.io/client-go/kubernetes/scheme"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/healthz"
    metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
 
    webappv1 "example.com/guestbook-operator/api/v1"
    "example.com/guestbook-operator/internal/controller"
)
 
var scheme = runtime.NewScheme()
 
func init() {
    utilruntime.Must(clientgoscheme.AddToScheme(scheme))
    utilruntime.Must(appsv1.AddToScheme(scheme))
    utilruntime.Must(corev1.AddToScheme(scheme))
    utilruntime.Must(webappv1.AddToScheme(scheme))
}
 
func main() {
    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme:                 scheme,
        Metrics:                metricsserver.Options{BindAddress: "0"},
        HealthProbeBindAddress: "0",
        LeaderElection:         false, // true in production
        LeaderElectionID:       "guestbook.example.com",
    })
    if err != nil {
        panic(err)
    }
 
    if err := (&controller.GuestbookReconciler{
        Client: mgr.GetClient(),
        Scheme: mgr.GetScheme(),
    }).SetupWithManager(mgr); err != nil {
        panic(err)
    }
 
    if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
        panic(err)
    }
    if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
        panic(err)
    }
 
    if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
        os.Exit(1)
    }
}

What this demonstrates:

• init() registers built-in and custom API types on a shared Scheme
• Manager options wire metrics, probes, and optional leader election
• Reconcilers receive the Manager's Client and Scheme, not raw client-go clients
• mgr.Start blocks until SIGINT/SIGTERM via SetupSignalHandler

Deep Dive

How It Works

• The Manager constructs a delegating client: reads hit the shared informer cache; writes go directly to the API server.
• AddToScheme links each Go type to its GroupVersionKind for decoding watches and lists.
• SetupWithManager on a reconciler registers For(), Owns(), and Watches() with the Manager's controller builder.
• RESTMapper inside the Manager resolves Guestbook to webapp.example.com/v1, Kind=Guestbook for generic API calls.

Manager Options at a Glance

Client vs Raw client-go

Go Notes

// Use APIReader when you must bypass cache (consistency-critical reads)
apiReader := mgr.GetAPIReader()
 
// Namespace-scoped operators: restrict cache in Manager options
ctrl.Options{
    Cache: cache.Options{
        DefaultNamespaces: map[string]cache.Config{
            "tenant-a": {},
        },
    },
}

Gotchas

• Forgetting AddToScheme for your CRD type - reconcile Get fails with "no kind is registered". Fix: call webappv1.AddToScheme(scheme) in init().
• Using the Client immediately before caches sync - first reconcile may see NotFound for existing objects. Fix: rely on requeue or use mgr.GetCache().WaitForCacheSync(ctx).
• Leader election off with multiple replicas - every Pod reconciles the same objects, causing duplicate work and races. Fix: enable LeaderElection in production Deployments.
• Binding metrics to :8080 without updating Service monitors - Prometheus misses scrapes. Fix: align BindAddress with chart Service ports and NetworkPolicy.
• Passing a fresh client.Client into reconcilers - bypasses shared cache and duplicates informers. Fix: always use mgr.GetClient().
• Mixing unstructured and typed clients without Scheme - decoding errors on generic objects. Fix: register all watched GVKs on the Manager Scheme.

Alternatives

FAQs

Related

• Kubernetes Operators Basics - scaffold and first reconcile
• Writing a Reconciler: ctrl.Request & Reconcile Loop - Reconcile return values
• Leader Election, Metrics & Operator Observability - probes and Prometheus
• Operator Testing with envtest & fake client - test Scheme setup
• Why Go Dominates the Kubernetes Operator Ecosystem - ecosystem context

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).