API concurrency: treat resourceVersion as an opaque token

A namespace/name locates an object, while its UID distinguishes that incarnation from a later object recreated with the same name. resourceVersion identifies a persisted version for API operations that use it. generation, where defined by a resource API, tracks specified changes according to that resource’s semantics. These fields are not interchangeable. An external resource associated only with a name may be mistaken for a new incarnation’s property after delete-and-recreate, even though the new object has a different UID.

For a normal version-checked object replacement, send the resourceVersion from the object you read. If another accepted update changed the current version first, the API server rejects the stale replacement with a conflict rather than silently losing that update. The retry should fetch current state and recompute the desired change. Replacing only the version token on an otherwise stale object would preserve the stale overwrite and defeat the purpose of the check. Bounded retries and appropriate backoff protect the control plane under contention.

A read-modify-write operation should preserve fields owned by other actors. Different patch formats have different merge and precondition semantics; an unconditional patch that overwrites a shared field can still lose logical updates. Server-Side Apply uses field-management semantics and conflict handling, which is a different mechanism from replacing an entire object with resourceVersion. Do not turn force ownership into a default retry policy. Decide which actor is responsible for each field, especially when a human and a controller both edit the same object.

A status subresource can separate supported status writes from desired-spec writes, but the resource definition determines what is exposed and validated. Do not assume that every status write can ignore concurrency or that any resourceVersion change means the desired configuration changed. Cache reads may lag a recent successful write, so a tight reread-and-overwrite loop can conflict unnecessarily. Use the client’s documented consistency behavior and observe the exact condition you need, rather than guessing freshness from a token that merely looks like a decimal number.

A conflict is often useful evidence that somebody else made progress. Distinguish it from authorization failure, invalid data, transport uncertainty, or deletion of the object. On NotFound, determine whether the desired external resource should be cleaned up or whether a new incarnation now occupies the same name; a UID check prevents confusing those cases. Preserve cancellation and maximum-attempt bounds, and expose persistent contention rather than silently spinning forever. A retry that changes the desired behavior is a semantic decision, not a mechanical networking trick.

The modular lab provides a warning against assuming numeric-looking labels encode unlimited progress. Reset, set m=8 and a=1, predict residues 0 through 7 and then zero again, and Step eight times. The lab’s labels are explicitly modular integers; Kubernetes resourceVersion is not modeled by them and is not claimed to wrap this way. The point is to read the actual contract before inferring order from labels. For real concurrency, replay the equality-token trace and verify the server’s conflict response.