2.14 Kubernetes Cluster State Architecture
Kubernetes Cluster State Architecture defines how clusters maintain and manage their operational state through structured control planes and node coordination.
Kubernetes Cluster State Architecture is the specific arrangement by which the entirety of a cluster's configuration and status is represented as a single, coherent body of data in etcd, describing how that single source of truth is read, cached, and propagated outward to every other component without any component maintaining an independently authoritative copy.
A Single Source of Truth Architecture
Every Component Derives State, None Originates It Independently
The cluster's state architecture is built around etcd as the sole originating store of durable state; every control plane component, node component, and client is architected to derive its view of the cluster from this one source, either directly or through the API server, never maintaining a separately authoritative record of its own.
Consequences of Centralization
This centralization is what allows the cluster to have a single, unambiguous answer to questions about current state, at the cost of etcd's own availability and consistency becoming a critical dependency for the functioning of the entire cluster.
Propagation Architecture
Watches as the Distribution Mechanism
State changes are architected to propagate outward from etcd through the API server's watch mechanism, allowing every interested component, whether a controller, the scheduler, or a kubelet, to receive updates as a continuous stream of events rather than by repeatedly polling for the current full state.
Caching Layers to Reduce Load
To avoid every watcher placing direct read load on etcd, the architecture layers an in-memory cache within the API server itself, and further caches within client libraries through informers, meaning most reads of cluster state are served from memory rather than requiring a round trip to the underlying store.
Consistency Guarantees Within the Architecture
Strong Consistency at the Store, Eventual Consistency Downstream
While etcd itself is architected to provide strongly consistent reads and writes among its own members, the propagation of that state outward to watchers is architected to be eventually consistent, meaning a component's cached view may briefly lag behind the true state recorded in etcd.
Resource Versions as a Consistency Signal
Every piece of cluster state carries a resource version, architected specifically so that clients can detect whether their cached view is current relative to a specific point in etcd's history, and so that concurrent updates to the same object can be safely detected and rejected rather than silently overwritten.
Why This Architecture Matters
A Foundation for Every Other Reconciliation Loop
Because every controller's reconciliation loop is architected to operate against this same propagated, eventually consistent view of state, understanding how state flows from etcd outward is foundational to understanding why controllers behave as level-triggered, self-correcting loops rather than as precise, one-shot event processors.