whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Official 1.17 Release Docs (#18011)

Browse Source 
* feat: graduate TaintNodesByCondition to GA (#17073)

* Promote StartupProbe to beta (enabled by default). (#17164)

* Watch bookmarks to GA (#17026)

* feat: graduate ScheduleDaemonSetPods to GA (#17350)

* Update Docker installation instructions (#17405)

* Use exact version numbers for installing Docker in Ubuntu (#17428)

* Move CSIMigration and CSIMigrationGCE to Beta in Kubernetes v1.17 (#17478)

* Promote NodeLease feature to GA (#17189)

* Update docs for csi topology ga (#17408)

* Update RunAsUsername to beta (#17460)

* doc:Update RunAsUsername to beta

* doc: update samples - kubernetes.io/os is no longer beta

* Updating based on review feedback

* Promote Node-specific volume limits to GA (#17432)

* Promote PodShareProcessNamespace to stable (#17192)

* Promote PodShareProcessNamespace to stable

* Add for_k8s_version to feature-state label

Co-Authored-By: Tim Bannister <tim@scalefactory.com>

* Readd version-check to shareProcessNamespace task

* Update service load balancer finalizer doc for GA (#17438)

* Update Topology Manager docs (#17451)

* Added information on how device plugins can take advantage
of Topology Manager
* Updated the Topology Manager documentation to include additionalinformation and update some out of date sections

* Fix broken Topology Manager link (#17746)

Part of What's Next Device Plugin section

* Update CRD defaulting docs for GA (#17450)

* Add documentation for VolumeSnapshot Beta (#17233)

* Updating EndpointSlice documentation for beta release in 1.17 (#17411)

* (docs/dualstack): v1.17 updates (#17457)

* Add placehold doc updates for dualstack in 1.17

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* Add Downward API and /etc/hosts Pod IP validation

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* remove addressed known issue via k/k pr 85246

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* Remove known issue and add flag as part of k/k 79993

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* remove follow up placeholders

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* Update verbiage

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* Make IP addressing consistent throughout the task

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* Update to status.podIPs

Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com>

* Update content/en/docs/tasks/network/validate-dual-stack.md

Use set instead of env

Co-Authored-By: Khaled Henidak (Kal) <khnidk@outlook.com>

* add topology.kubernetes.io/zone, topology.kubernetes.io/region and node.kubernetes.io/instance-type labels to docs (#17498)

Signed-off-by: Andrew Sy Kim <kiman@vmware.com>

* Service topology alpha documentation (#17459)

* Update list of feature flags for in-tree plugins migrated to CSI (#17533)

Signed-off-by: Deep Debroy <ddebroy@docker.com>

* Update Node concept for TaintNodesByCondition going GA (#17577)

* feat: graduate ResourceQuotaScopeSelectors to GA in 1.17 (#17554)

* kubeadm: update the upgrade documentation for 1.17 (#17587)

* doc: Simplify Windows deployments with RuntimeClass (#16697)

* doc: Simplify Windows deployments with RuntimeClass

* Updating on review feedback

* doc: Adding windows-build label from enhancement 1301

* update doc for kubelet option --reserved-cpus (#17648)

* feat: update TaintNodesByCondition in feature gates table (#17377)

* Update docs for v1 resource quota configuration (#17547)

* AdmissionConfiguration v1 (#17548)

* Update WebhookAdmissionConfiguration examples (#17549)

* Update AWS EBS Migration Feature state (#16126)

* Add resource version section to api-concepts documentation (#16910)

* Add Resource Version semantics section to api concepts

* Clarify risks of going back in time, add details about compaction and watch cache sizes

* Apply suggestions from liggitt

Co-Authored-By: Jordan Liggitt <jordan@liggitt.net>

* remove pesudocode, apply feedback

* Fix typo

* Clarify equality rules

* Cleanup kubectl generators docs (#17609)

* Write ReplicationController without a space

* Drop mentioning unsupported cluster versions

* Fix capitalization for “API group”

* Tweak wording

* Avoid using deprecated generator in example

* add Antrea description in dev-1.17 (#17919)

* Promote VolumeSubpathEnvExpansion to GA

* Reference Documentation for the Kubernetes API for 1.17 (#18019)

* Update feature-gates.md (#18033)

* Reference Documentation for kubectl Commands for 1.17 (#18017)

* Update for v1.17 (#18034)

* Update config.toml(release-1.17) for 1.17 (#18031)
This commit is contained in:
Damini Satya
2019-12-10 05:41:29 +05:30
committed by Kubernetes Prow Robot
parent cf925bb688
commit dff2f7b960
63 changed files with 62955 additions and 443 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/reference/using-api/api-concepts.md
+63 -4
View File
@@ -51,7 +51,7 @@ The verbs supported for each subresource will differ depending on the object - s
## Efficient detection of changes
To enable clients to build a model of the current state of a cluster, all Kubernetes object resource types are required to support consistent lists and an incremental change notification feed called a **watch**. Every Kubernetes object has a `resourceVersion` field representing the version of that resource as stored in the underlying database. When retrieving a collection of resources (either namespace or cluster scoped), the response from the server will contain a `resourceVersion` value that can be used to initiate a watch against the server. The server will return all changes (creates, deletes, and updates) that occur after the supplied `resourceVersion`. This allows a client to fetch the current state and then watch for changes without missing any updates. If the client watch is disconnected they can restart a new watch from the last returned `resourceVersion`, or perform a new collection request and begin again.
To enable clients to build a model of the current state of a cluster, all Kubernetes object resource types are required to support consistent lists and an incremental change notification feed called a **watch**. Every Kubernetes object has a `resourceVersion` field representing the version of that resource as stored in the underlying database. When retrieving a collection of resources (either namespace or cluster scoped), the response from the server will contain a `resourceVersion` value that can be used to initiate a watch against the server. The server will return all changes (creates, deletes, and updates) that occur after the supplied `resourceVersion`. This allows a client to fetch the current state and then watch for changes without missing any updates. If the client watch is disconnected they can restart a new watch from the last returned `resourceVersion`, or perform a new collection request and begin again. See [Resource Version Semantics](#resource-versions) for more detail.
For example:
@@ -89,8 +89,6 @@ A given Kubernetes server will only preserve a historical list of changes for a
### Watch bookmarks
{{< feature-state for_k8s_version="v1.16" state="beta" >}}
To mitigate the impact of short history window, we introduced a concept of `bookmark` watch event. It is a special kind of event to pass an information that all changes up to a given `resourceVersion` client is requesting has already been send. Object returned in that event is of the type requested by the request, but only `resourceVersion` field is set, e.g.:
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
@@ -108,7 +106,7 @@ To mitigate the impact of short history window, we introduced a concept of `book
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "12746"} }
}
`Bookmark` events can be requested by `allowWatchBookmarks=true` option in watch requests, but clients shouldn't assume bookmarks are returned at any specific interval, nor may they assume the server will send any `bookmark` event. Since version 1.16, watch bookmarks feature is enabled by default.
`Bookmark` events can be requested by `allowWatchBookmarks=true` option in watch requests, but clients shouldn't assume bookmarks are returned at any specific interval, nor may they assume the server will send any `bookmark` event.
## Retrieving large results sets in chunks
@@ -646,3 +644,64 @@ Server Side Apply is a beta feature, so it is enabled by default. To turn this
you need to include the `--feature-gates ServerSideApply=false` flag when
starting `kube-apiserver`. If you have multiple `kube-apiserver` replicas, all
should have the same flag setting.
## Resource Versions
Resource versions are strings that identify the server's internal version of an object. Resource versions can be used by clients to determine when objects have changed, or to express data consistency requirements when getting, listing and watching resources. Resource versions must be treated as opaque by clients and passed unmodified back to the server. For example, clients must not assume resource versions are numeric, and may only compare two resource version for equality (i.e. must not compare resource versions for greater-than or less-than relationships).
### ResourceVersion in metadata
Clients find resource versions in resources, including the resources in watch events, and list responses returned from the server:
[v1.meta/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#objectmeta-v1-meta) - The `metadata.resourceVersion` of a resource instance identifies the resource version the instance was last modified at.
[v1.meta/ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#listmeta-v1-meta) - The `metadata.resourceVersion` of a resource collection (i.e. a list response) identifies the resource version at which the list response was constructed.
### The ResourceVersion Parameter
The get, list and watch operations support the `resourceVersion` parameter.
The exact meaning of this parameter differs depending on the operation and the value of the resource version.
For get and list, the semantics of resource version are:
**Get:**
| resourceVersion unset | resourceVersion="0" | resourceVersion="{non-zero version}" |
|-----------------------|---------------------|--------------------------------------|
| Most Recent | Any | Not older than |
**List:**
| paging | resourceVersion unset | resourceVersion="0" | resourceVersion="{non-zero version}" |
|-----------|-----------------------|---------------------|--------------------------------------|
| no limit | Most Recent | Any | Not older than |
| limit="n" | Most Recent | Any | Exact |
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 resource version is preferred, but any data not older than this resource version may be served.
- **Exact:** Return data at the exact resource version provided.
For watch, the semantics of resource version are:
**Watch:**
| resourceVersion unset | resourceVersion="0" | resourceVersion="{non-zero version}" |
|-------------------------------------|----------------------------|--------------------------------------|
| Get State and Start at Most Recent | Get State and Start at Any | Start at Exact |
The meaning of the watch semantics are:
- **Get State and Start at Most Recent:** Start a watch at the most recent resource version, which must be consistent (i.e. served from etcd via a quorum read). To establish initial state, the watch begins with synthetic “Added” events of all resources instances that exist at the starting resource version. All following watch events are for all changes that occured after the resource version the watch started at.
- **Get State and Start at Any:** Warning: Watches initialize this way may return arbitrarily stale data! Please review this semantic before using it, and favor the other semantics where possible. Start a watch at any resource version, the most recent resource version available is preferred, but not required; any starting resource version is allowed. It is possible for the watch to start 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 start a watch with this semantic. To establish initial state, the watch begins with synthetic “Added” events for all resources instances that exist at the starting resource version. All following watch events are for all changes that occured after the resource version the watch started at.
- **Start at Exact:** Start a watch at an exact resource version. The watch events are for all changes after the provided resource version. Unlike "Get State and Start at Most Recent" and "Get State and Start at Any", the watch is not started with synthetic "Added" events for the provided resource version. The client is assumed to already have the initial state at the starting resource version since the client provided the resource version.
### "410 Gone" responses
Servers are not required to serve all older resource versions and may return a HTTP `410 (Gone)` status code if a client requests a resourceVersion older than the server has retained. Clients must be able to tolerate `410 (Gone)` responses. See [Efficient detection of changes](#efficient-detection-of-changes) for details on how to handle `410 (Gone)` responses when watching resources.
For example, the kube-apiserver periodically compacts old resource versions from etcd based on its `--etcd-compaction-interval` setting. Also, the kube-apiserver's watch cache keeps `--watch-cache-sizes` resource versions in each resource cache. It depends on if a request is served from cache on which one of these limits applies, but if a resource version is unavailable in the one that applies, a `410 (Gone)` will be returned by the kube-apiserver.