Skip to content

Commit

Permalink
Apply feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
jpbetz committed Dec 11, 2019
1 parent 8d00a0f commit 0e35578
Showing 1 changed file with 7 additions and 7 deletions.
14 changes: 7 additions & 7 deletions content/en/docs/reference/using-api/api-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -673,19 +673,19 @@ For get and list, the semantics of resource version are:

**List:**

| paging | resourceVersion unset | resourceVersion="0" | resourceVersion="{value other than 0}" |
|-------------------------------|-----------------------|---------------------|----------------------------------------|
| limit unset | Most Recent | Any | Not older than |
| limit="n", continue unset | Most Recent | Any | Exact |
| limit="n", continue="<token>" | Continue Token | Continue Token | Continue Token |
| paging | resourceVersion unset | resourceVersion="0" | resourceVersion="{value other than 0}" |
|-------------------------------|-----------------------|------------------------------------------------|----------------------------------------|
| limit unset | Most Recent | Any | Not older than |
| limit="n", continue unset | Most Recent | Any | Exact |
| limit="n", continue="<token>" | Continue Token, Exact | Invalid, but treated as Continue Token, Exact | Invalid, HTTP `400 (Bad Request)` |

The meaning of the get and list semantics are:

- **Most Recent:** Return data at the most recent resource version. The returned data must be consistent (i.e. served from etcd via a quorum read).
- **Any:** Return data at any resource version. The newest available resource version is preferred, but strong consistency is not required; data at any resource version may be served. It is possible for the request to return data at a much older resource version that the client has previously observed, particularly in high availabiliy configurations, due to partitions or stale caches. Clients that cannot tolerate this should not use this semantic.
- **Not older than:** Return data at least as new as the provided resource version. The newest available data is preferred, but any data not older than this resource version may be served. Note that this ensures only that the objects returned are no older than they were at the time of the provided resource version. The resource version in the `ObjectMeta` of individual object may be older than the provide resource version so long it is for the latest modification to the object at the time of the provided resource version.
- **Exact:** Return data at the exact resource version provided.
- **Continue Token:** Return data at the resource version provided to the initial paginated list call. The returned Continue Tokens are responsible for keeping track of the initially provided resource version for all subsequent list calls.
- **Continue Token, Exact:** Return data at the resource version of the initial paginated list call. The returned Continue Tokens are responsible for keeping track of the initially provided resource version for all paginated list calls after the initial paginated list call.

For watch, the semantics of resource version are:

Expand All @@ -709,4 +709,4 @@ For example, the kube-apiserver periodically compacts old resource versions from

### Unavailable resource versions

Servers are not required to serve unrecognized resource versions. List and Get requests for unrecognized resource versions may wait briefly for the resource version to become available, should timeout with a `504 (Gateway Timeout)` if the provided resource versions does not become available in a resonable amount of time, and may respond with a `Retry-After` response header indicating how many seconds a client should wait before retrying the request. Currently the kube-apiserver also identifies these responses with a "Too large resource version" message. Watch requests for a unrecognized resource version may wait indefinitely for the resource version to become available.
Servers are not required to serve unrecognized resource versions. List and Get requests for unrecognized resource versions may wait briefly for the resource version to become available, should timeout with a `504 (Gateway Timeout)` if the provided resource versions does not become available in a resonable amount of time, and may respond with a `Retry-After` response header indicating how many seconds a client should wait before retrying the request. Currently the kube-apiserver also identifies these responses with a "Too large resource version" message. Watch requests for a unrecognized resource version may wait indefinitely (until the request timeout) for the resource version to become available.

0 comments on commit 0e35578

Please sign in to comment.