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

[zh] Resync using-api/api-concepts.md

pull/48522/head
windsonsea 2024-10-24 09:25:48 +08:00
parent c63a9ca115
commit 851c27fd59
1 changed files with 73 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
content/zh-cn/docs/reference/using-api/api-concepts.md
View File

@ -21,7 +21,7 @@ primary resources via the standard HTTP verbs (POST, PUT, PATCH, DELETE,
GET).
For some resources, the API includes additional subresources that allow
fine grained authorization (such as separate views for Pod details and
fine-grained authorization (such as separate views for Pod details and
log retrievals), and can accept and serve those resources in different
representations for convenience or efficiency.
-->
@ -117,7 +117,7 @@ example: Nodes), and so their names must be unique across the whole cluster.
### API verbs
Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH,
and DELETE. Kubernetes also uses its own verbs, which are often written lowercase to distinguish
and DELETE. Kubernetes also uses its own verbs, which are often written in lowercase to distinguish
them from HTTP verbs.
Kubernetes uses the term **list** to describe returning a [collection](#collections) of
@ -184,9 +184,12 @@ The following paths are used to retrieve collections and resources:
* Namespace-scoped resources:
* `GET /apis/GROUP/VERSION/RESOURCETYPE` - return the collection of all instances of the resource type across all namespaces
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` - return collection of all instances of the resource type in NAMESPACE
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` - return the instance of the resource type with NAME in NAMESPACE
* `GET /apis/GROUP/VERSION/RESOURCETYPE` - return the collection of all
instances of the resource type across all namespaces
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` - return
collection of all instances of the resource type in NAMESPACE
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` -
return the instance of the resource type with NAME in NAMESPACE
-->
你还可以访问资源集合（例如：列出所有 Node）。以下路径用于检索集合和资源：
@ -198,8 +201,10 @@ The following paths are used to retrieve collections and resources:
* 名字空间作用域的资源：
* `GET /apis/GROUP/VERSION/RESOURCETYPE` - 返回所有名字空间中指定资源类型的全部实例的集合
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` - 返回名字空间 NAMESPACE 内给定资源类型的全部实例的集合
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` - 返回名字空间 NAMESPACE 中给定资源类型的名称为 NAME 的实例
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` -
返回名字空间 NAMESPACE 内给定资源类型的全部实例的集合
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` -
返回名字空间 NAMESPACE 中给定资源类型的名称为 NAME 的实例
<!--
Since a namespace is a cluster-scoped resource type, you can retrieve the list
@ -334,7 +339,9 @@ Kubernetes API 默认使用 [JSON](https://www.json.org/json-en.html) 来编码
<!--
### YAML resource encoding {#yaml-encoding}
Kubernetes also supports the [`application/yaml`](https://www.rfc-editor.org/rfc/rfc9512.html) media type for both requests and responses. [`YAML`](https://yaml.org/) can be used for defining Kubernetes manifests and API interactions.
Kubernetes also supports the [`application/yaml`](https://www.rfc-editor.org/rfc/rfc9512.html)
media type for both requests and responses. [`YAML`](https://yaml.org/)
can be used for defining Kubernetes manifests and API interactions.
For example:
-->
@ -408,7 +415,7 @@ Kubernetes uses an envelope wrapper to encode [Protobuf](https://protobuf.dev/)
That wrapper starts with a 4 byte magic number to help identify content in disk or in etcd as Protobuf
(as opposed to JSON). The 4 byte magic number data is followed by a Protobuf encoded wrapper message, which
describes the encoding and type of the underlying object. Within the Protobuf wrapper message,
the inner object data is recorded using the `raw` field of Unknown (see the [IDL](##protobuf-encoding-idl)
the inner object data is recorded using the `raw` field of Unknown (see the [IDL](#protobuf-encoding-idl)
for more detail).
-->
### Kubernetes Protobuf 编码 {#protobuf-encoding}
@ -417,7 +424,7 @@ Kubernetes 使用封套形式来对 [Protobuf](https://protobuf.dev/) 响应进
封套外层由 4 个字节的特殊数字开头，便于从磁盘文件或 etcd 中辩识 Protobuf
格式的（而不是 JSON）数据。这个 4 字节的特殊数字后跟一个 Protobuf 编码的封套消息，
此消息描述了下层对象的编码和类型。在 Protobuf 封套消息中，内部对象数据使用 Unknown 的
`raw` 字段进行记录（有关细节参见 [IDL](##protobuf-encoding-idl)）。
`raw` 字段进行记录（有关细节参见 [IDL](#protobuf-encoding-idl)）。
<!--
For example:
@ -989,7 +996,7 @@ of 500 pods at a time, request those chunks as follows:
```
<!--
2. Continue the previous call, retrieving the next set of 500 pods.
1. Continue the previous call, retrieving the next set of 500 pods.
-->
2. 继续前面的调用，返回下一组 500 个 Pod：
@ -1013,7 +1020,7 @@ of 500 pods at a time, request those chunks as follows:
```
<!--
3. Continue the previous call, retrieving the last 253 pods.
1. Continue the previous call, retrieving the last 253 pods.
-->
3. 继续前面的调用，返回最后 253 个 Pod：
@ -1076,10 +1083,10 @@ collections of different types of resource. Collections have a kind
named for the resource kind, with `List` appended.
When you query the API for a particular type, all items returned by that query are
of that type.
For example, when you **list** Services, the collection response
of that type. For example, when you **list** Services, the collection response
has `kind` set to
[`ServiceList`](/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceList); each item in that collection represents a single Service. For example:
[`ServiceList`](/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceList);
each item in that collection represents a single Service. For example:
-->
## 集合 {#collections}
@ -1095,6 +1102,7 @@ has `kind` set to
```
GET /api/v1/services
```
```yaml
{
"kind": "ServiceList",
@ -1447,20 +1455,23 @@ validation are `Ignore`, `Warn` (default), and `Strict`.
从 1.25 开始，当使用可以提交数据的 HTTP 动词（`POST`、`PUT` 和 `PATCH`）时，
将通过服务器上的校验检测到对象中无法识别或重复的字段。
校验的级别可以是 `Ignore`、`Warn`（默认值） 和 `Strict` 之一。
<!--
`Ignore`
: The API server succeeds in handling the request as it would without the erroneous fields
being set, dropping all unknown and duplicate fields and giving no indication it
has done so.
being set, dropping all unknown and duplicate fields and giving no indication it
has done so.
-->
`Ignore`
: 使 API 服务器像没有遇到错误字段一样成功处理请求，丢弃所有的未知字段和重复字段，并且不发送丢弃字段的通知。
<!--
`Warn`
: (Default) The API server succeeds in handling the request, and reports a
warning to the client. The warning is sent using the `Warning:` response header,
adding one warning item for each unknown or duplicate field. For more
information about warnings and the Kubernetes API, see the blog article
[Warning: Helpful Warnings Ahead](/blog/2020/09/03/warnings/).
warning to the client. The warning is sent using the `Warning:` response header,
adding one warning item for each unknown or duplicate field. For more
information about warnings and the Kubernetes API, see the blog article
[Warning: Helpful Warnings Ahead](/blog/2020/09/03/warnings/).
-->
`Warn`
:（默认值）使 API 服务器成功处理请求，并向客户端发送告警信息。告警信息通过 `Warning:` 响应头发送，
@ -1468,10 +1479,11 @@ information about warnings and the Kubernetes API, see the blog article
可参阅博文[告警：增加实用告警功能](/zh-cn/blog/2020/09/03/warnings/)。
<!--
`Strict`
: The API server rejects the request with a 400 Bad Request error when it
detects any unknown or duplicate fields. The response message from the API
server specifies all the unknown or duplicate fields that the API server has
detected.
detects any unknown or duplicate fields. The response message from the API
server specifies all the unknown or duplicate fields that the API server has
detected.
-->
`Strict`
: API 服务器检测到任何未知字段或重复字段时，拒绝处理请求并返回 400 Bad Request 错误。
@ -1646,7 +1658,8 @@ request is made. Some of these fields are:
* `name`: if `generateName` is set, `name` will have a unique random name
* `creationTimestamp` / `deletionTimestamp`: records the time of creation/deletion
* `UID`: [uniquely identifies](/docs/concepts/overview/working-with-objects/names/#uids) the object and is randomly generated (non-deterministic)
* `UID`: [uniquely identifies](/docs/concepts/overview/working-with-objects/names/#uids)
the object and is randomly generated (non-deterministic)
* `resourceVersion`: tracks the persisted version of the object
* Any field set by a mutating admission controller
* For the `Service` resource: Ports or IP addresses that the kube-apiserver assigns to Service objects
@ -1724,7 +1737,8 @@ Kubernetes 使用该 `resourceVersion` 信息，这样 API 服务器可以检测
<!--
Instead of sending a PUT request, the client can send an instruction to the API
server to **patch** an existing resource. A **patch** is typically appropriate
if the change that the client wants to make isn't conditional on the existing data. Clients that need effective detection of lost updates should consider
if the change that the client wants to make isn't conditional on the existing data.
Clients that need effective detection of lost updates should consider
making their request conditional on the existing `resourceVersion` (either HTTP PUT or HTTP PATCH),
and then handle any retries that are needed in case there is a conflict.
@ -1908,10 +1922,10 @@ A **patch** update is helpful, because:
<!--
However:
* you need more local (client) logic to build the patch; it helps a lot if you have
a library implementation of JSON Patch, or even for making a JSON Patch specifically against Kubernetes
* as the author of client software, you need to be careful when building the patch
(the HTTP request body) not to drop fields (the order of operations matters)
* You need more local (client) logic to build the patch; it helps a lot if you have
a library implementation of JSON Patch, or even for making a JSON Patch specifically against Kubernetes.
* As the author of client software, you need to be careful when building the patch
(the HTTP request body) not to drop fields (the order of operations matters).
-->
然而：
@ -1932,28 +1946,28 @@ Server-Side Apply has some clear benefits:
* A single round trip: it rarely requires making a `GET` request first.
* and you can still detect conflicts for unexpected changes
* you have the option to force override a conflict, if appropriate
* Client implementations are easy to make
* Client implementations are easy to make.
* You get an atomic create-or-update operation without extra effort
(similar to `UPSERT` in some SQL dialects)
(similar to `UPSERT` in some SQL dialects).
-->
* 仅需一次轮询：通常无需先执行 `GET` 请求。
* 并且你仍然可以检测到意外更改造成的冲突
* 合适的时候，你可以选择强制覆盖冲突
* 客户端实现简单
* 客户端实现简单。
* 你可以轻松获得原子级别的 create 或 update 操作，无需额外工作
（类似于某些 SQL 语句中的 `UPSERT`）
（类似于某些 SQL 语句中的 `UPSERT`）。
<!--
However:
* Server-Side Apply does not work at all for field changes that depend on a current value of the object
* Server-Side Apply does not work at all for field changes that depend on a current value of the object.
* You can only apply updates to objects. Some resources in the Kubernetes HTTP API are
not objects (they do not have a `.metadata` field), and Server-Side Apply
is only relevant for Kubernetes objects.
-->
然而：
* 服务器端应用不适合依赖对象当前值的字段更改
* 服务器端应用不适合依赖对象当前值的字段更改。
* 你只能更新对象。Kubernetes HTTP API 中的某些资源不是对象（它们没有 `.metadata` 字段），
并且服务器端应用只能用于 Kubernetes 对象。
@ -1986,9 +2000,12 @@ API 客户端只能比较两个资源版本的相等性（这意味着你不能
Clients find resource versions in resources, including the resources from the response
stream for a **watch**, or when using **list** to enumerate resources.
[v1.meta/ObjectMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#objectmeta-v1-meta) - The `metadata.resourceVersion` of a resource instance identifies the resource version the instance was last modified at.
[v1.meta/ObjectMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#objectmeta-v1-meta) -
The `metadata.resourceVersion` of a resource instance identifies the resource version the instance was last modified at.
[v1.meta/ListMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#listmeta-v1-meta) - The `metadata.resourceVersion` of a resource collection (the response to a **list**) identifies the resource version at which the collection was constructed.
[v1.meta/ListMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#listmeta-v1-meta) -
The `metadata.resourceVersion` of a resource collection (the response to a **list**) identifies the
resource version at which the collection was constructed.
-->
### metadata 中的 `resourceVersion` {#resourceVersion-in-metadata}
@ -2080,30 +2097,29 @@ This table explains the behavior of **list** requests with various combinations
下表解释了具有各种 `resourceVersion` 和 `resourceVersionMatch` 组合的 **list** 请求的行为：
<!--
| resourceVersionMatch param | paging params | resourceVersion not set | resourceVersion="0" | resourceVersion="{value other than 0}" |
|---------------------------------------|-------------------------------|-----------------------|-------------------------------------------|----------------------------------------|
| _unset_ | _limit unset_ | Most Recent | Any | Not older than |
| _unset_ | limit=\<n\>, _continue unset_ | Most Recent | Any | Exact |
| _unset_ | limit=\<n\>, continue=\<token\> | Continue Token, Exact | Invalid, treated as Continue Token, Exact | Invalid, HTTP `400 Bad Request` |
| `resourceVersionMatch=Exact` | _limit unset_ | Invalid | Invalid | Exact |
| `resourceVersionMatch=Exact` | limit=\<n\>, _continue unset_ | Invalid | Invalid | Exact |
| `resourceVersionMatch=NotOlderThan` | _limit unset_ | Invalid | Any | Not older than |
| `resourceVersionMatch=NotOlderThan` | limit=\<n\>, _continue unset_ | Invalid | Any | Not older than |
| resourceVersionMatch param | paging params | resourceVersion not set | resourceVersion="0" | resourceVersion="{value other than 0}" |
|----------------------------|---------------|-------------------------|---------------------|----------------------------------------|
| _unset_ | _limit unset_ | Most Recent | Any | Not older than |
| _unset_ | limit=\<n\>, _continue unset_ | Most Recent | Any | Exact |
| _unset_ | limit=\<n\>, continue=\<token\>| Continue Token, Exact | Invalid, treated as Continue Token, Exact | Invalid, HTTP `400 Bad Request` |
| `resourceVersionMatch=Exact` | _limit unset_ | Invalid | Invalid | Exact |
| `resourceVersionMatch=Exact` | limit=\<n\>, _continue unset_ | Invalid | Invalid | Exact |
| `resourceVersionMatch=NotOlderThan` | _limit unset_ | Invalid | Any | Not older than |
| `resourceVersionMatch=NotOlderThan` | limit=\<n\>, _continue unset_ | Invalid | Any | Not older than |
{{</* /table */>}}
-->
{{< table caption="list 操作的 resourceVersionMatch 与分页参数" >}}
| resourceVersionMatch 参数 | 分页参数 | resourceVersion 未设置 | resourceVersion="0" | resourceVersion="\<非零值\>" |
|-----------------------------------------|---------------------------------|-------------------------|-----------------------------------------|----------------------------------|
| **未设置** | **limit 未设置** | 最新版本 | 任意版本 | 不老于指定版本 |
| **未设置** | limit=\<n\>, **continue 未设置** | 最新版本 | 任意版本 | 精确匹配 |
| **未设置** | limit=\<n\>, continue=\<token\> | 从 token 开始、精确匹配 | 非法请求，视为从 token 开始、精确匹配 | 非法请求，返回 HTTP `400 Bad Request` |
| `resourceVersionMatch=Exact` [1] | **limit 未设置** | 非法请求 | 非法请求 | 精确匹配 |
| `resourceVersionMatch=Exact` [1] | limit=\<n\>, **continue 未设置** | 非法请求 | 非法请求 | 精确匹配 |
| `resourceVersionMatch=NotOlderThan` [1] | **limit 未设置** | 非法请求 | 任意版本 | 不老于指定版本 |
| `resourceVersionMatch=NotOlderThan` [1] | limit=\<n\>, **continue 未设置** | 非法请求 | 任意版本 | 不老于指定版本 |
| resourceVersionMatch 参数 | 分页参数 | resourceVersion 未设置 | resourceVersion="0" | resourceVersion="\<非零值\>" |
|--------------------------|---------|-----------------------|---------------------|-----------------------------|
| **未设置** | **limit 未设置** | 最新版本 | 任意版本 | 不老于指定版本 |
| **未设置** | limit=\<n\>, **continue 未设置** | 最新版本 | 任意版本 | 精确匹配 |
| **未设置** | limit=\<n\>, continue=\<token\> | 从 token 开始、精确匹配 | 非法请求，视为从 token 开始、精确匹配 | 非法请求，返回 HTTP `400 Bad Request` |
| `resourceVersionMatch=Exact` [1] | **limit 未设置** | 非法请求 | 非法请求 | 精确匹配 |
| `resourceVersionMatch=Exact` [1] | limit=\<n\>, **continue 未设置** | 非法请求 | 非法请求 | 精确匹配 |
| `resourceVersionMatch=NotOlderThan` [1] | **limit 未设置** | 非法请求 | 任意版本 | 不老于指定版本 |
| `resourceVersionMatch=NotOlderThan` [1] | limit=\<n\>, **continue 未设置** | 非法请求 | 任意版本 | 不老于指定版本 |
{{< /table >}}