Mount Cangshan soared into the clouds with ten thousand precipitous cliffs. From its mist-wreathed crags down to the mountain base stretched thousands of acres of terraced paddy fields, interconnected by a sprawling, dizzying labyrinth of stone irrigation canals.

Perched upon the highest summit above the sea of clouds sat the Heavenly Reservoir Office, which governed the primary water gates of the entire mountain. The reservoir masters commanded colossal iron sluices controlling the downstream torrents, recording the active water levels of every weir in cinnabar upon a monolithic stone cliff. Scattered across the ridges and foothills lived thirty mountain water wardens, each entrusted with a specific agrarian domain: the Rice Terrace Warden, the Tea Grove Warden, the Fish Pond Warden, the Flood Diversion Warden, and many more.

In earlier reigns, the thirty wardens suffered under an agonizing, backward ritual. Every quarter-hour, each warden dispatched a fleet-footed young apprentice with a paper lantern, sprinted up five thousand sheer stone steps in the burning sun, and hammered frantically on the heavy timber gates of the Heavenly Reservoir, shouting: “How many inches is Sluice 42 open? Has Sluice 88 begun diverting water?” The gatehouse of the Heavenly Reservoir was perpetually choked with thirty panting apprentices shouting at once. The reservoir scribes were driven to madness, their ink repeatedly questioned before it could even dry upon the stone cliff. Worse still, running up and down five thousand precipitous steps consumed half a day. By the time an exhausted apprentice staggered back to the foothills, mountain squalls had altered the reservoir sluices three times over. Wardens opened irrigation canals based on six-hour-old intelligence, either drowning tender rice seedlings in flash floods or leaving tea terraces parched to dust.

The newly appointed Chief Water Master, Gu, surveyed the mountainside and beheld the misery. He summoned the thirty wardens to the Listening Spring Pavilion at the mountain midpoint, erecting the grand Waterside Gallery and instituting the revolutionary Statute of the Reflected Bronze Mirrors:

First, “Mirror Facing the Peak: The Initial Full Survey and Following the Lights” (Reflector: List and Watch). In the center of the Waterside Gallery, Gu mounted an eight-foot polished bronze convex mirror, aligned directly with the semaphore beacon atop the Heavenly Reservoir. No apprentice was ever permitted to climb the mountain again. At the beginning of each day, the gallery scribe adjusted the bronze mirror once, scanning the grand chalk-board atop the peak through a telescope to transcribe the full opening positions of all sluices and the active imperial day-mark (resourceVersion)—this was the Initial Full Survey (List). From that heartbeat onward, the summit signallers waved dual-colored flags and manipulated polished bronze flashers only when a sluice actually moved, flashing a single, instantaneous optical code across the sky: “Sluice 42, raised one inch, Day-mark 1001”—this was Following the Lights (Watch). The bronze mirror at the foothills remained perfectly still, reflecting changes when they occurred and resting silent when water flowed undisturbed. Never again did a human soul climb five thousand steps for news.

Second, “The Flowing Bamboo Chute: Sequencing the Deltas” (DeltaFIFO). On storm-swept nights, summit flash-codes flickered across the sky in furious succession. To prevent downstream scribes from dropping flashes or scrambling sequences, an inclined bamboo chute (DeltaFIFO) was suspended beneath the mirror. Whenever a flash-code beamed down from the peak, a lookout engraved a wooden slip with the nature of the change (Added, Altered, Closed, Verified) and dropped it into the bamboo chute. The slips tumbled down the smooth rail in strict chronological order, guaranteeing that no matter how violently the storm raged, all transitions remained safely queued, never skipping a single delta or scrambling the order of events.

Third, “The Sandbox Model: Immediate Local Reflection” (Indexer and Local Cache). At the bottom of the bamboo chute sat a dedicated keeper. As each wooden slip tumbled into his basket, he adjusted a small bronze lever on an intricate, water-filled physical sandbox model of all thousand terraces resting on the pavilion table (Indexer). This sandbox model was partitioned into labeled grooves by mountain valley (namespace) and crop variety (labels), creating an exact, live, microsecond replica of every stream on Mount Cangshan. Henceforth, whenever the Rice Warden or Lotus Warden needed to verify water levels, he did not look at the summit, nor did he run up the peaks—he walked two steps to the table, dipped his fingers into the sandbox groove, and read the water level instantly. A microsecond local inspection, with zero mountain journeys and zero burden on the summit!

Fourth, “The Shared Gallery and the Signal Tally” (SharedInformer and Workqueue). Most ingenious of all, this grand bronze mirror and tabletop sandbox were shared communally (Shared) among all thirty wardens. The summit signalman beamed only a single flash-code down the mountain, yet thirty wardens beheld the updated reality in the sandbox simultaneously. When a specific terrace required physical ditch-clearing, the keeper dropped a small numbered wooden token (Workqueue Key) into that warden’s private wicker tray. The warden collected his token and tended his fields at his own pace, unhurried, independent, and free of panic.

Ever after, silence reigned outside the Heavenly Reservoir on the peaks, while the thousands of acres across the valleys flourished in emerald splendor. The mountain farmers sang across the terraced heights: “To storm the peak for tidings was a thousand souls undone (Direct Polling); To catch the gleaming water-lights is mastery begun (SharedInformer). The first broad scan reveals the realm (List); the dancing flashes tell the tale (Watch). The bamboo chute preserves the stream (DeltaFIFO); the sandbox mirrors hill and vale (Indexer).”

— — —

What it is

By now the architecture is unmistakable: this is the master engine behind the entire Kubernetes control plane and every production-grade Custom Controller and Operator: the SharedInformer architecture in client-go (encompassing Reflector, DeltaFIFO, Indexer, and the Workqueue).

In a Kubernetes cluster, controllers (such as the ReplicaSetController, DeploymentController, Kube-Scheduler, Kubelet, and hundreds of custom CRD Operators) must continuously track the latest desired and actual states of resources (Pods, Nodes, Services) to drive their Reconciliation Loops. The naive approach—represented by the apprentices sprinting up the mountain—would be polling: if every controller repeatedly issued GET /api/v1/pods against the API Server, etcd and the control plane would collapse under $O(C \times N)$ network serialization overhead. Even with long-lived streaming Watches, absent a localized caching layer, controllers would still saturate the network fetching object details.

The SharedInformer framework resolves this through a sophisticated five-stage pipeline:

1. Reflector (The Mirror Facing the Peak · List and Watch): The Reflector is the front-line sentinel communicating with the API Server.
   • List (Full Survey): Upon initialization, the Reflector issues an initial HTTP List request to retrieve a full snapshot of all existing target resources, capturing the snapshot’s global sequence marker: the resourceVersion.
   • Watch (Following the Lights): Immediately following the List, the Reflector establishes a persistent HTTP Chunked streaming Watch connection anchored to that resourceVersion. The API Server sends only lightweight, incremental event envelopes (ADDED, MODIFIED, DELETED) when state transitions occur. If the network drops, the Reflector automatically resumes the Watch from its last observed resourceVersion; if the version has expired from etcd history (HTTP 410 Gone), it gracefully falls back to a fresh List to re-establish the baseline.
2. DeltaFIFO (The Flowing Bamboo Chute · Buffered Sequencing): Events captured by the Reflector are not shoved directly into business logic. Instead, they are wrapped as Delta objects (carrying the action type Added/Updated/Deleted/Sync and the object payload) and queued into a thread-safe, buffered queue called DeltaFIFO. DeltaFIFO ensures that rapid, bursting updates to the same resource are delivered in strict chronological sequence, absorbing sudden event avalanches (e.g., thousands of Pods terminating simultaneously) without dropping state or overwhelming downstream consumers.
3. Indexer and ThreadSafeStore (The Tabletop Sandbox · In-Memory Cache): A background consumer loop pops deltas from DeltaFIFO and updates an in-memory, thread-safe cache called the Indexer (backed by ThreadSafeStore). The Indexer computes multi-dimensional indexes using custom indexing functions (e.g., indexing Pods by Namespace, NodeName, or Label selectors). Crucially, all subsequent read queries from controllers (lister.List() or lister.Get()) are served 100% out of local RAM in microseconds, generating zero network traffic and zero load against the API Server and etcd!
4. SharedInformer and SharedProcessor (The Shared Gallery · Shared Watch and Fanout): Multiple controllers within a process often monitor the same resource type (e.g., both Kube-Scheduler and NodeController watch Nodes). Rather than instantiating separate watch connections and duplicate in-memory caches, a SharedInformer multiplexes a single Reflector connection and a single shared Indexer cache. Its internal SharedProcessor fans out change events to all registered handlers (OnAdd, OnUpdate, OnDelete).
5. Workqueue (The Signal Tally · Decoupling and Rate-Limited Retries): When an event handler fires, it does not execute complex reconciliation logic inline. Instead, it extracts only the resource’s coordinate—the lightweight string Key (namespace/name, such as default/nginx-pod)—and pushes it into a RateLimitingQueue (Workqueue). Worker goroutines dequeue keys and pull the freshest state from the local Indexer to reconcile. If reconciliation fails, the Workqueue applies exponential backoff retries, elegantly decoupling asynchronous event notification from state convergence.

Why it matters

SharedInformer is the technical foundation that allowed Kubernetes to scale from hundreds of containers to fleets of millions of workloads:

1. Impervious Shield for API Server and etcd: By absorbing more than 90% of cluster queries into local in-memory Indexers, thousands of Operator loops can query resources endlessly without causing control plane latency degradation or etcd lock starvation.
2. Level-Triggered State Convergence: By queuing only the resource Key into the Workqueue rather than the full delta payload, the controller’s reconciliation worker always inspects the freshest, live state currently sitting in the local Indexer. If network packets or intermediate updates were dropped during transient disconnections, the controller naturally converges on the ultimate desired state regardless.
3. Memory Footprint Optimization via Shared Caches: Consolidating multiple controller watches into a single SharedInformer eliminates duplicated in-memory object allocations, keeping Kubernetes controllers lean and cache-coherent.

Metaphor mapping

• The Heavenly Reservoir on the mountain summit and stone wall → The Kubernetes Control Plane (API Server and etcd state store)
• Apprentices repeatedly climbing five thousand stone steps to ask water levels → Controllers blindly polling the API Server, crippling etcd under linear load
• Eight-foot polished bronze convex mirror in the gallery → The client component watching remote state (Reflector)
• Morning telescope survey transcribing full initial levels and day-mark → Reflector’s initial full baseline fetch (List) and capturing resourceVersion
• Flashing semaphore flags and bronze mirrors signaling only changes → HTTP Chunked streaming deltas (Watch)
• Inclined bamboo chute buffering slips in sequence → Thread-safe buffered queue absorbing bursts (DeltaFIFO)
• Tabletop miniature sandbox model reflecting all mountain streams → Local in-memory indexed cache (Indexer / ThreadSafeStore)
• Wardens dipping fingers into sandbox to read levels in an instant → Controllers executing lister.Get() / List() against local RAM with zero network calls
• Thirty wardens sharing a single bronze mirror and sandbox → Multiple controllers sharing one connection and cache (SharedInformer)
• Dropping numbered wooden tokens into the warden’s private wicker tray → Event handlers enqueuing lightweight namespace/name keys into the Workqueue