Document why all REST calls return resourceVersion

[abonas]

What is the meaning (and the purpose) of PodList resourceVersion? - isn't it just the collection of current pods? In which circumstances does it change? when a new pod is added? when any pod is updated? Is there any use case when the REST api user should refer to the collection's resourceVersion and/or pass this version to the server? (when do users pass a list of pods to the server?)
thank you.

[bgrant0607]

Great questions. Keep them coming. We're going to overhaul the documentation soon.

Regarding this issue, see #1184. The value of resourceVersion is currently etcd's sequencer. Think of it as a logical clock the apiserver can use to order requests.

[abonas]

@bgrant0607 I would say that the client side shouldn't be aware/consider server side ordering issues - that should be completely a server side implementation detail how the requests are ordered. Clients should be exposed solely to information they can/should do something about (create an entity, change a property on an entity, etc.)
Is there any specific usecase that the client should take care of a collection's resourceVersion or it can be safely ignored? Can you give an example when the client needs to pass it back to server at all?
Thank you!

[lavalamp]

More specifically, the resourceVersion in a list is the resourceVersion at which one must start watching if one wants to be certain not to miss any changes.

[lavalamp]

Clients should treat it as an opaque field, of course.

[smarterclayton]

I think for future implementors of alternate backends we should document we assume that the underlying store supports snapshot isolation reads, and the resource version is the global transaction id (or resource local transaction id) that supports a subsequent read. Since we like watch as a pattern, and we depend on it from a number of places.