Kubernetes List and Watch Model

Kubernetes List and Watch Model is the combined pattern of retrieving a complete snapshot of a resource collection and then subscribing to a continuous stream of subsequent changes to that same collection, forming the foundational data-access pattern nearly every controller, cache, and client tool in the Kubernetes ecosystem is built on top of. Rather than repeatedly polling the API server for changes, clients establish their view of cluster state once through a list, and then keep that view current cheaply and efficiently through a long-lived watch connection.

The list Operation

Retrieving a Point-in-Time Snapshot

A list request returns every currently existing object in a resource collection (optionally filtered by label or field selector), along with a resourceVersion in the response's metadata representing the point in the API server's history at which that snapshot was taken, giving the client both the data and a precise marker for where to resume observing changes from.

Pagination for Large Collections

For collections too large to return efficiently in a single response, list requests support pagination through a limit parameter and a returned continue token, allowing a client to retrieve the full collection across multiple requests without the API server needing to hold an unbounded amount of data in memory for a single response.

The watch Operation

Establishing a Long-Lived Stream

A watch request, issued with a resourceVersion (typically the one returned by a preceding list), opens a long-lived HTTP connection over which the API server streams a sequence of events — ADDED, MODIFIED, DELETED, and occasionally BOOKMARK — representing every change to the collection that has occurred since that resourceVersion, in the order they occurred.

Why Watch Is Preferred Over Polling

Because watch delivers changes as they happen rather than requiring the client to repeatedly re-list and diff, it dramatically reduces both the latency between a change occurring and a client learning about it, and the load placed on the API server compared to a polling-based alternative, which is essential at the scale of clusters running many controllers each needing near-real-time visibility into cluster state.

resourceVersion as the Resumption Token

Resuming After a Dropped Connection

If a watch connection drops — due to a network interruption, an API server restart, or the connection's own configured timeout — a well-behaved client reconnects with a new watch request using the last resourceVersion it successfully processed, allowing it to resume exactly where it left off without missing intervening changes or needing to reprocess ones it already saw.

Handling an Expired resourceVersion

Because the API server (through etcd) does not retain change history indefinitely, a watch request for a resourceVersion too far in the past will fail with a "too old resource version" error (HTTP 410 Gone), and the correct response is for the client to perform a fresh list to reestablish a current snapshot and resourceVersion, then resume watching from that new point.

The Informer Pattern Built on List and Watch

Combining List and Watch Into a Local Cache

Client libraries commonly wrap the raw list and watch operations into an "informer," which performs an initial list to populate a local, in-memory cache (often backed by a data structure supporting indexed lookups), then transitions to a watch to keep that cache continuously synchronized, exposing the cache to application code as a fast, always-current local read path that avoids hitting the API server for every single read.

Relist as a Reliability Backstop

Informers periodically perform a full relist even while a watch connection remains healthy, as a defense against subtle bugs or edge cases where individual watch events might be missed without the connection itself visibly failing, trading some additional API server load for stronger consistency guarantees over long-running processes.

Bookmarks and Efficiency

The BOOKMARK Event Type

A BOOKMARK event carries no object change but advances the resourceVersion a client has observed, sent periodically by the API server on otherwise quiet watch connections so that a client reconnecting after a restart has a recent resourceVersion to resume from even if no actual object changes occurred during that period, reducing the chance of needing a full relist purely due to watch idleness.