This article explores the internal mechanics of the Kubernetes controller-runtime library, specifically focusing on how the local cache functions via list-watch patterns. It clarifies common misconceptions regarding consistency, memory usage, and API interactions when developing custom Kubernetes controllers. The piece provides actionable guidance on optimizing reconciler performance and managing cache-related trade-offs.
Key points
The controller-runtime uses a local in-memory cache for Get/List operations rather than hitting the API server directly.
Writes (Create, Update, Patch, Delete) bypass the cache and are sent directly to the API server.
Cache consistency is eventually achieved via the watch mechanism, which introduces the possibility of stale reads.
Memory consumption is directly tied to the size of the local cache and the number of indexes configured.
APIReader should only be used for bypasses when absolute consistency or specialized reads are required.