kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Clean up using-api/api-concepts.md

pull/49147/head
windsonsea 2024-12-18 10:49:56 +08:00
parent ce8a338661
commit 5607a0b815
1 changed files with 58 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
content/en/docs/reference/using-api/api-concepts.md
View File

@ -68,11 +68,11 @@ Almost all object resource types support the standard HTTP verbs - GET, POST, PU
and DELETE. Kubernetes also uses its own verbs, which are often written in lowercase to distinguish and DELETE. Kubernetes also uses its own verbs, which are often written in lowercase to distinguish
them from HTTP verbs. them from HTTP verbs.
Kubernetes uses the term **list** to describe returning a [collection](#collections) of Kubernetes uses the term **list** to describe the action of returning a [collection](#collections) of
resources to distinguish from retrieving a single resource which is usually called resources, to distinguish it from retrieving a single resource which is usually called
a **get**. If you sent an HTTP GET request with the `?watch` query parameter, a **get**. If you sent an HTTP GET request with the `?watch` query parameter,
Kubernetes calls this a **watch** and not a **get** (see Kubernetes calls this a **watch** and not a **get**
[Efficient detection of changes](#efficient-detection-of-changes) for more details). (see [Efficient detection of changes](#efficient-detection-of-changes) for more details).
For PUT requests, Kubernetes internally classifies these as either **create** or **update** For PUT requests, Kubernetes internally classifies these as either **create** or **update**
based on the state of the existing object. An **update** is different from a **patch**; the based on the state of the existing object. An **update** is different from a **patch**; the
@ -335,17 +335,16 @@ Accept: application/vnd.kubernetes.protobuf, application/json
{{< feature-state feature_gate_name="CBORServingAndStorage" >}} {{< feature-state feature_gate_name="CBORServingAndStorage" >}}
With the `CBORServingAndStorage` [feature With the `CBORServingAndStorage` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
gate](/docs/reference/command-line-tools-reference/feature-gates/) enabled, request and response enabled, request and response bodies for all built-in resource types and all resources defined by a
bodies for all built-in resource types and all resources defined by a {{< glossary_tooltip {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} may be encoded to the
term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} may be encoded to the [CBOR](https://www.rfc-editor.org/rfc/rfc8949) binary data format. CBOR is also supported at the
[CBOR](https://www.rfc-editor.org/rfc/rfc8949) binary data format. CBOR is also supported at the {{< {{< glossary_tooltip text="aggregation layer" term_id="aggregation-layer" >}} if it is enabled in
glossary_tooltip text="aggregation layer" term_id="aggregation-layer" >}} if it is enabled in
individual aggregated API servers. individual aggregated API servers.
Clients should indicate the IANA media type `application/cbor` in the `Content-Type` HTTP request Clients should indicate the IANA media type `application/cbor` in the `Content-Type` HTTP request
header when the request body contains a single CBOR [encoded data header when the request body contains a single CBOR
item](https://www.rfc-editor.org/rfc/rfc8949.html#section-1.2-4.2), and in the `Accept` HTTP request [encoded data item](https://www.rfc-editor.org/rfc/rfc8949.html#section-1.2-4.2), and in the `Accept` HTTP request
header when prepared to accept a CBOR encoded data item in the response. API servers will use header when prepared to accept a CBOR encoded data item in the response. API servers will use
`application/cbor` in the `Content-Type` HTTP response header when the response body contains a `application/cbor` in the `Content-Type` HTTP response header when the response body contains a
CBOR-encoded object. CBOR-encoded object.
@ -355,8 +354,8 @@ CBOR, the response body will be a [CBOR Sequence](https://www.rfc-editor.org/rfc
`Content-Type` HTTP response header will use the IANA media type `application/cbor-seq`. Each entry `Content-Type` HTTP response header will use the IANA media type `application/cbor-seq`. Each entry
of the sequence (if any) is a single CBOR-encoded watch event. of the sequence (if any) is a single CBOR-encoded watch event.
In addition to the existing `application/apply-patch+yaml` media type for YAML-encoded [server-side In addition to the existing `application/apply-patch+yaml` media type for YAML-encoded
apply configurations](#patch-and-apply), API servers that enable CBOR will accept the [server-side apply configurations](#patch-and-apply), API servers that enable CBOR will accept the
`application/apply-patch+cbor` media type for CBOR-encoded server-side apply configurations. There `application/apply-patch+cbor` media type for CBOR-encoded server-side apply configurations. There
is no supported CBOR equivalent for `application/json-patch+json` or `application/merge-patch+json`, is no supported CBOR equivalent for `application/json-patch+json` or `application/merge-patch+json`,
or `application/strategic-merge-patch+json`. or `application/strategic-merge-patch+json`.
@ -388,7 +387,7 @@ For example:
1. List all of the pods in a given namespace. 1. List all of the pods in a given namespace.
``` ```http
GET /api/v1/namespaces/test/pods GET /api/v1/namespaces/test/pods
--- ---
200 OK 200 OK
@ -407,7 +406,7 @@ For example:
_test_ namespace. Each change notification is a JSON document. The HTTP response body _test_ namespace. Each change notification is a JSON document. The HTTP response body
(served as `application/json`) consists a series of JSON documents. (served as `application/json`) consists a series of JSON documents.
``` ```http
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245 GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
--- ---
200 OK 200 OK
@ -444,7 +443,7 @@ to a given `resourceVersion` the client is requesting have already been sent. Th
document representing the `BOOKMARK` event is of the type requested by the request, document representing the `BOOKMARK` event is of the type requested by the request,
but only includes a `.metadata.resourceVersion` field. For example: but only includes a `.metadata.resourceVersion` field. For example:
``` ```http
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
--- ---
200 OK 200 OK
@ -500,7 +499,7 @@ is 10245 and there are two pods: `foo` and `bar`. Then sending the following req
_consistent read_ by setting empty resource version using `resourceVersion=`) could result _consistent read_ by setting empty resource version using `resourceVersion=`) could result
in the following sequence of events: in the following sequence of events:
``` ```http
GET /api/v1/namespaces/test/pods?watch=1&sendInitialEvents=true&allowWatchBookmarks=true&resourceVersion=&resourceVersionMatch=NotOlderThan GET /api/v1/namespaces/test/pods?watch=1&sendInitialEvents=true&allowWatchBookmarks=true&resourceVersion=&resourceVersionMatch=NotOlderThan
--- ---
200 OK 200 OK
@ -541,7 +540,7 @@ can be saved and the latency can be reduced.
To verify if `APIResponseCompression` is working, you can send a **get** or **list** request to the To verify if `APIResponseCompression` is working, you can send a **get** or **list** request to the
API server with an `Accept-Encoding` header, and check the response size and headers. For example: API server with an `Accept-Encoding` header, and check the response size and headers. For example:
``` ```http
GET /api/v1/pods GET /api/v1/pods
Accept-Encoding: gzip Accept-Encoding: gzip
--- ---
@ -592,7 +591,7 @@ of 500 pods at a time, request those chunks as follows:
1. List all of the pods on a cluster, retrieving up to 500 pods each time. 1. List all of the pods on a cluster, retrieving up to 500 pods each time.
``` ```http
GET /api/v1/pods?limit=500 GET /api/v1/pods?limit=500
--- ---
200 OK 200 OK
@ -613,7 +612,7 @@ of 500 pods at a time, request those chunks as follows:
1. Continue the previous call, retrieving the next set of 500 pods. 1. Continue the previous call, retrieving the next set of 500 pods.
``` ```http
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
--- ---
200 OK 200 OK
@ -634,7 +633,7 @@ of 500 pods at a time, request those chunks as follows:
1. Continue the previous call, retrieving the last 253 pods. 1. Continue the previous call, retrieving the last 253 pods.
``` ```http
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2 GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
--- ---
200 OK 200 OK
@ -682,7 +681,7 @@ has `kind` set to
[`ServiceList`](/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceList); [`ServiceList`](/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceList);
each item in that collection represents a single Service. For example: each item in that collection represents a single Service. For example:
``` ```http
GET /api/v1/services GET /api/v1/services
``` ```
@ -779,7 +778,7 @@ type.
For example, list all of the pods on a cluster in the Table format. For example, list all of the pods on a cluster in the Table format.
``` ```http
GET /api/v1/pods GET /api/v1/pods
Accept: application/json;as=Table;g=meta.k8s.io;v=v1 Accept: application/json;as=Table;g=meta.k8s.io;v=v1
--- ---
@ -800,7 +799,7 @@ For API resource types that do not have a custom Table definition known to the c
plane, the API server returns a default Table response that consists of the resource's plane, the API server returns a default Table response that consists of the resource's
`name` and `creationTimestamp` fields. `name` and `creationTimestamp` fields.
``` ```http
GET /apis/crd.example.com/v1alpha1/namespaces/default/resources GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
--- ---
200 OK 200 OK
@ -844,7 +843,7 @@ Accept: application/json;as=Table;g=meta.k8s.io;v=v1, application/json
When you **delete** a resource this takes place in two phases. When you **delete** a resource this takes place in two phases.
1. _finalization_ 1. _finalization_
2. removal 1. removal
```yaml ```yaml
{ {
@ -857,7 +856,8 @@ When you **delete** a resource this takes place in two phases.
} }
``` ```
When a client first sends a **delete** to request the removal of a resource, the `.metadata.deletionTimestamp` is set to the current time. When a client first sends a **delete** to request the removal of a resource,
the `.metadata.deletionTimestamp` is set to the current time.
Once the `.metadata.deletionTimestamp` is set, external controllers that act on finalizers Once the `.metadata.deletionTimestamp` is set, external controllers that act on finalizers
may start performing their cleanup work at any time, in any order. may start performing their cleanup work at any time, in any order.
@ -896,8 +896,12 @@ the **delete** and **unsafe-delete-ignore-read-errors** verbs on the given resou
{{< /note >}} {{< /note >}}
A resource is considered corrupt if it can not be successfully retrieved from the A resource is considered corrupt if it can not be successfully retrieved from the
storage due to a) transformation error (for example: decryption failure), or b) the object storage due to:
failed to decode. The API server first attempts a normal deletion, and if it fails with
- transformation error (for example: decryption failure), or
- the object failed to decode.
The API server first attempts a normal deletion, and if it fails with
a _corrupt resource_ error then it triggers the force delete. A force **delete** operation a _corrupt resource_ error then it triggers the force delete. A force **delete** operation
is unsafe because it ignores finalizer constraints, and skips precondition checks. is unsafe because it ignores finalizer constraints, and skips precondition checks.
@ -944,9 +948,8 @@ an HTTP request.
These situations are: These situations are:
1. The field is unrecognized because it is not in the resource's OpenAPI schema. (One 1. The field is unrecognized because it is not in the resource's OpenAPI schema. (One
exception to this is for {{< glossary_tooltip exception to this is for {{< glossary_tooltip term_id="CustomResourceDefinition" text="CRDs" >}}
term_id="CustomResourceDefinition" text="CRDs" >}} that explicitly choose not to prune unknown that explicitly choose not to prune unknown fields via `x-kubernetes-preserve-unknown-fields`).
fields via `x-kubernetes-preserve-unknown-fields`).
1. The field is duplicated in the object. 1. The field is duplicated in the object.
### Validation for unrecognized or duplicate fields {#setting-the-field-validation-level} ### Validation for unrecognized or duplicate fields {#setting-the-field-validation-level}
@ -954,8 +957,8 @@ These situations are:
{{< feature-state feature_gate_name="ServerSideFieldValidation" >}} {{< feature-state feature_gate_name="ServerSideFieldValidation" >}}
From 1.25 onward, unrecognized or duplicate fields in an object are detected via From 1.25 onward, unrecognized or duplicate fields in an object are detected via
validation on the server when you use HTTP verbs that can submit data (`POST`, `PUT`, and `PATCH`). Possible levels of validation on the server when you use HTTP verbs that can submit data (`POST`, `PUT`, and `PATCH`).
validation are `Ignore`, `Warn` (default), and `Strict`. Possible levels of validation are `Ignore`, `Warn` (default), and `Strict`.
`Ignore` `Ignore`
: The API server succeeds in handling the request as it would without the erroneous fields : The API server succeeds in handling the request as it would without the erroneous fields
@ -1003,7 +1006,7 @@ Client-side validation will be removed entirely in a future version of kubectl.
{{< note >}} {{< note >}}
Prior to Kubernetes 1.25 `kubectl --validate` was used to toggle client-side validation on or off as Prior to Kubernetes 1.25, `kubectl --validate` was used to toggle client-side validation on or off as
a boolean flag. a boolean flag.
{{< /note >}} {{< /note >}}
@ -1056,7 +1059,7 @@ effects on any request marked as dry runs.
Here is an example dry-run request that uses `?dryRun=All`: Here is an example dry-run request that uses `?dryRun=All`:
``` ```http
POST /api/v1/namespaces/test/pods?dryRun=All POST /api/v1/namespaces/test/pods?dryRun=All
Content-Type: application/json Content-Type: application/json
Accept: application/json Accept: application/json
@ -1333,10 +1336,10 @@ Any
Most recent Most recent
: Return data at the most recent resource version. The returned data must be : Return data at the most recent resource version. The returned data must be
consistent (in detail: served from etcd via a quorum read). consistent (in detail: served from etcd via a quorum read).
For etcd v3.4.31+ and v3.5.13+ Kubernetes {{< skew currentVersion >}} serves “most recent” reads from the _watch cache_: For etcd v3.4.31+ and v3.5.13+, Kubernetes {{< skew currentVersion >}} serves “most recent” reads from the _watch cache_:
an internal, in-memory store within the API server that caches and mirrors the state of data an internal, in-memory store within the API server that caches and mirrors the state of data
persisted into etcd. Kubernetes requests progress notification to maintain cache consistency against persisted into etcd. Kubernetes requests progress notification to maintain cache consistency against
the etcd persistence layer. Kubernetes versions v1.28 through to v1.30 also supported this the etcd persistence layer. Kubernetes v1.28 through to v1.30 also supported this
feature, although as Alpha it was not recommended for production nor enabled by default until the v1.31 release. feature, although as Alpha it was not recommended for production nor enabled by default until the v1.31 release.
Not older than Not older than
@ -1349,7 +1352,7 @@ Not older than
Exact Exact
: Return data at the exact resource version provided. If the provided `resourceVersion` is : Return data at the exact resource version provided. If the provided `resourceVersion` is
unavailable, the server responds with HTTP 410 "Gone". For **list** requests to servers that honor the unavailable, the server responds with HTTP `410 Gone`. For **list** requests to servers that honor the
`resourceVersionMatch` parameter, this guarantees that the collection's `.metadata.resourceVersion` `resourceVersionMatch` parameter, this guarantees that the collection's `.metadata.resourceVersion`
is the same as the `resourceVersion` you requested in the query string. That guarantee does is the same as the `resourceVersion` you requested in the query string. That guarantee does
not apply to the `.metadata.resourceVersion` of any items within that collection. not apply to the `.metadata.resourceVersion` of any items within that collection.
@ -1370,7 +1373,7 @@ the object is when served.
{{< /note >}} {{< /note >}}
When using `resourceVersionMatch=NotOlderThan` and limit is set, clients must When using `resourceVersionMatch=NotOlderThan` and limit is set, clients must
handle HTTP 410 "Gone" responses. For example, the client might retry with a handle HTTP `410 Gone` responses. For example, the client might retry with a
newer `resourceVersion` or fall back to `resourceVersion=""`. newer `resourceVersion` or fall back to `resourceVersion=""`.
When using `resourceVersionMatch=Exact` and `limit` is unset, clients must When using `resourceVersionMatch=Exact` and `limit` is unset, clients must
@ -1395,11 +1398,7 @@ For **watch**, the semantics of resource version are:
The meaning of those **watch** semantics are: The meaning of those **watch** semantics are:
Get State and Start at Any Get State and Start at Any
: {{< caution >}} Watches initialized this way may return arbitrarily stale : Start a **watch** at any resource version; the most recent resource version
data. Please review this semantic before using it, and favor the other semantics
where possible.
{{< /caution >}}
Start a **watch** at any resource version; the most recent resource version
available is preferred, but not required. Any starting resource version is 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 allowed. It is possible for the **watch** to start at a much older resource
version that the client has previously observed, particularly in high availability version that the client has previously observed, particularly in high availability
@ -1410,6 +1409,12 @@ Get State and Start at Any
watch events are for all changes that occurred after the resource version the watch events are for all changes that occurred after the resource version the
**watch** started at. **watch** started at.
{{< caution >}}
**watches** initialized this way may return arbitrarily stale
data. Please review this semantic before using it, and favor the other semantics
where possible.
{{< /caution >}}
Get State and Start at Most Recent Get State and Start at Most Recent
: Start a **watch** at the most recent resource version, which must be consistent : Start a **watch** at the most recent resource version, which must be consistent
(in detail: served from etcd via a quorum read). To establish initial state, (in detail: served from etcd via a quorum read). To establish initial state,
@ -1450,8 +1455,8 @@ then the API server may either:
should wait before retrying the request. should wait before retrying the request.
If you request a resource version that an API server does not recognize, the If you request a resource version that an API server does not recognize, the
kube-apiserver additionally identifies its error responses with a "Too large resource kube-apiserver additionally identifies its error responses with a message
version" message. `Too large resource version`.
If you make a **watch** request for an unrecognized resource version, the API server If you make a **watch** request for an unrecognized resource version, the API server
may wait indefinitely (until the request timeout) for the resource version to become may wait indefinitely (until the request timeout) for the resource version to become