---
title: "How the controller-runtime Cache Actually Works, and Why Your Controller Does Not Crash the API Server"
url: https://daily.dev/posts/how-the-controller-runtime-cache-actually-works-and-why-your-controller-does-not-crash-the-api-serv-zx4undfxm
source_url: https://kubernetes.io/blog/2026/07/29/controller-runtime-cache-explained
type: article
source: "Kubernetes"
published: 2026-07-29T23:54:12.561Z
updated: 2026-07-30T02:01:50.880Z
tags: ["kubernetes", "golang"]
reading_time: 32
upvotes: 0
comments: 0
language: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How the controller-runtime Cache Actually Works, and Why Your Controller Does Not Crash the API Server

**[Kubernetes](https://daily.dev/sources/k8s)** · 32 min read · 0 upvotes · 0 comments

## Summary

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.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://kubernetes.io/blog/2026/07/29/controller-runtime-cache-explained>

## Similar posts on daily.dev

- [Unlocking efficiency: A guide to operator cache configuration on Red Hat OpenShift and Kubernetes](https://daily.dev/posts/unlocking-efficiency-a-guide-to-operator-cache-configuration-on-red-hat-openshift-and-kubernetes-rrynupdxu) · Red Hat Developer · 0 upvotes · 0 comments
- [5 anti-patterns that cause Kubernetes operator vulnerabilities](https://daily.dev/posts/5-anti-patterns-that-cause-kubernetes-operator-vulnerabilities-tjsfjyvka) · Red Hat Developer · 6 upvotes · 0 comments

---

Tags: [#kubernetes](https://daily.dev/tags/kubernetes), [#golang](https://daily.dev/tags/golang)

[View this post on daily.dev](https://daily.dev/posts/how-the-controller-runtime-cache-actually-works-and-why-your-controller-does-not-crash-the-api-serv-zx4undfxm)