A deep dive into how controller-runtime's cache works internally for Kubernetes controller authors. The cache is built on client-go primitives — Reflector, DeltaFIFO, and Indexer — and is the foundational operating model, not an optimization. Key insights: r.Get() and r.List() read from an in-memory store populated via list+watch, never hitting the API server directly; writes go straight to the API server; and the cache is fully warmed before the first Reconcile runs. The post covers common mistakes (expecting read-after-write consistency, mutating shared objects in predicates/handlers, misunderstanding resync vs relist), how to use IndexField for O(1) lookups instead of O(n) scans, selective caching with namespace/label/field selectors and Transform to reduce memory, PartialObjectMetadata for metadata-only watches, and when to use APIReader for guaranteed freshness.
