Describe how a Kubernetes client keeps an up-to-date view of a set of objects using the list-then-watch pattern, and what the resourceVersion value returned by the API server means in that flow.

## The problem A controller needs a current view of, say, every Pod in a namespace. Polling with a LIST every second is correct but brutally expensive: full serialization of every object, repeated, from every client in the cluster. The list-then-watch pattern gives the same correctness at a tiny fraction of the cost. ## The flow 1. **LIST.** `GET /api/v1/namespaces/x/pods` returns a PodList. Its `metadata.resourceVersion` is the version of the *collection*: the point in the change stream at which this snapshot is consistent. 2. **WATCH from that point.** `GET /api/v1/namespaces/x/pods?watch=true&resourceVersion=<rv>` opens a long-lived streaming response (chunked HTTP, or an HTTP/2 stream). The server sends nothing for the past and then one JSON event per change: `{"type":"ADDED"|"MODIFIED"|"DELETED"|"BOOKMARK", "object": {...}}`. 3. **Apply events locally.** The client mutates its cached copy per event. Each delivered object carries its own resourceVersion; the client remembers the newest one it processed so it can resume from there. 4. **On disconnect, resume.** Reconnect with the last processed resourceVersion. If the server can still serve from that point, the stream continues with no gap and no relist. 5. **On 410 Gone, relist.** If the requested version is older than the server's retained history, the server returns `410 Gone: too old resource version`. The only correct response is to LIST again (fresh snapshot, fresh version) and rewatch. The client must resync its cache wholesale, because it cannot know what it missed. ## resourceVersion semantics The field appears on both individual objects and on list responses, and it is **opaque to clients**. The rules that matter: - Every write bumps the object's resourceVersion. Reads do not. - Values are only meaningful within one cluster; never store them long-term or compare across clusters. - Do not treat them as numbers. They are strings that happen to look numeric in the current implementation; ordering guarantees exist for the watch stream, not for arbitrary comparison of two objects. - Passing `resourceVersion=0` on a LIST means "any reasonably recent version you have, cheapest possible" — served from the API server's watch cache, possibly slightly stale. Omitting it requests a fully consistent read. That difference matters: `0` is cheap but can return data older than a write you just made. - The same value doubles as the optimistic-concurrency token on updates, which is why a stale one produces a 409 Conflict. ## Why 410 Gone exists The API server keeps a bounded window of recent changes in its watch cache (and etcd itself compacts old revisions). A client that was disconnected or paused for a long time may ask to resume from a version that has fallen out of that window. Rather than silently skipping events — which would leave the client permanently wrong — the server refuses with 410 and forces an honest resync. ## What the libraries do You rarely write this by hand. client-go's **Reflector** implements exactly this loop: list, record version, watch, apply events into a store, handle 410 by relisting, reconnect with backoff. Informers build on it. Writing it yourself is a known source of subtle bugs — mishandling 410, treating resourceVersion as an integer, or assuming a watch never breaks.