Merge pull request #36267 from Michelle951/michelle07

[zh] sync content/zh-cn/docs/reference/using-api/api-concepts.md

Author: k8s-ci-robot

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

@@ -21,14 +21,14 @@ 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 a separating viewing details for a Pod from
-retrieving its logs), and can accept and serve those resources in different
+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.
 -->
 Kubernetes API 是通过 HTTP 提供的基于资源 (RESTful) 的编程接口。
 它支持通过标准 HTTP 动词（POST、PUT、PATCH、DELETE、GET）检索、创建、更新和删除主要资源。
 
-对于某些资源，API 包括额外的子资源，允许细粒度授权（例如将 Pod 的查看详细信息与检索其日志分开），
+对于某些资源，API 包括额外的子资源，允许细粒度授权（例如：将 Pod 的详细信息与检索日志分开），
 为了方便或者提高效率，可以以不同的表示形式接受和服务这些资源。
 
 <!--
@@ -39,12 +39,14 @@ effectively cache, track, and synchronize the state of resources.
 You can view the [API reference](/docs/reference/kubernetes-api/) online,
 or read on to learn about the API in general.
 -->
-Kubernetes 支持通过 **watchs** 实现高效的资源变更通知。
+Kubernetes 支持通过 **watch** 实现高效的资源变更通知。
 Kubernetes 还提供了一致的列表操作，以便 API 客户端可以有效地缓存、跟踪和同步资源的状态。
 
 你可以在线查看 [API 参考](/zh-cn/docs/reference/kubernetes-api/)，
 或继续阅读以了解 API 的一般信息。
 
+<!-- body -->
+
 <!--
 ## Kubernetes API terminology {#standard-api-terminology}
 
@@ -251,13 +253,14 @@ For example:
 <!--
 1. List all of the pods in a given namespace.
 -->
-1. 列举给定名字空间中的所有 Pods：
+1. 列举给定名字空间中的所有 Pod：
 
    ```console
    GET /api/v1/namespaces/test/pods
    ---
    200 OK
    Content-Type: application/json
+
    {
      "kind": "PodList",
      "apiVersion": "v1",
@@ -434,7 +437,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. 列举集群中所有 Pod，每次接收至多 500 个 Pods：
+1. 列举集群中所有 Pod，每次接收至多 500 个 Pod：
 
    ```console
    GET /api/v1/pods?limit=500
@@ -448,15 +451,17 @@ of 500 pods at a time, request those chunks as follows:
      "metadata": {
        "resourceVersion":"10245",
        "continue": "ENCODED_CONTINUE_TOKEN",
+       "remainingItemCount": 753,
        ...
      },
      "items": [...] // returns pods 1-500
    }
    ```
+
 <!--
 2. Continue the previous call, retrieving the next set of 500 pods.
 -->
-2. 继续前面的调用，返回下一组 500 个 Pods：
+2. 继续前面的调用，返回下一组 500 个 Pod：
 
    ```console
    GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
@@ -470,6 +475,7 @@ of 500 pods at a time, request those chunks as follows:
      "metadata": {
        "resourceVersion":"10245",
        "continue": "ENCODED_CONTINUE_TOKEN_2",
+       "remainingItemCount": 253,
        ...
      },
      "items": [...] // returns pods 501-1000
@@ -479,9 +485,9 @@ of 500 pods at a time, request those chunks as follows:
 <!--
 3. Continue the previous call, retrieving the last 253 pods.
 -->
-3. 继续前面的调用，返回最后 253 个 Pods：
+3. 继续前面的调用，返回最后 253 个 Pod：
 
-  ```console
+   ```console
    GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
    ---
    200 OK
@@ -497,7 +503,7 @@ of 500 pods at a time, request those chunks as follows:
      },
      "items": [...] // returns pods 1001-1253
    }
-  ```
+   ```
 
 <!--
 Notice that the `resourceVersion` of the collection remains constant across each request,
@@ -683,7 +689,7 @@ Kubernetes API 实现标准的 HTTP 内容类型（Content Type）协商：为 `
 传入一个值为 `application/json;as=Table;g=meta.k8s.io;v=v1` 的 `Accept`
 头部即可请求服务器以 Table 的内容类型返回对象。
 
-例如，以 Table 格式列举集群中所有 Pods：
+例如，以 Table 格式列举集群中所有 Pod：
 
 ```console
 GET /api/v1/pods
@@ -753,7 +759,7 @@ extensions, you should make requests that specify multiple content types in the
 如果你正在实现使用 Table 信息并且必须针对所有资源类型（包括扩展）工作的客户端，
 你应该在 `Accept` 请求头中指定多种内容类型的请求。例如：
 
-```
+```console
 Accept: application/json;as=Table;g=meta.k8s.io;v=v1, application/json
 ```
 
@@ -1032,6 +1038,165 @@ Kubernetes API 动词 **get**、**create**、**apply**、**update**、**patch**
 相比之下，Kubernetes API 动词 **list** 和 **watch** 允许获取多个资源，
 而 **deletecollection** 允许删除多个资源。
 
+<!--
+## Field validation
+-->
+## 字段校验    {#field-validation}
+
+<!--
+Kubernetes always validates the type of fields. For example, if a field in the
+API is defined as a number, you cannot set the field to a text value. If a field
+is defined as an array of strings, you can only provide an array. Some fields
+allow you to omit them, other fields are required. Omitting a required field
+from an API request is an error.
+-->
+Kubernetes 总是校验字段的类型。例如，如果 API 中的某个字段被定义为数值，
+你就不能将该字段设置为文本类型的值。如果某个字段被定义为字符串数组，你只能提供数组。
+有些字段可以忽略，有些字段必须填写。忽略 API 请求中的必填字段会报错。
+
+<!--
+If you make a request with an extra field, one that the cluster's control plane
+does not recognize, then the behavior of the API server is more complicated.
+-->
+如果请求中带有集群控制面无法识别的额外字段，API 服务器的行为会更加复杂。
+
+<!--
+By default, the API server drops fields that it does not recognize
+from an input that it receives (for example, the JSON body of a `PUT` request).
+-->
+默认情况下，如果接收到的输入信息中含有 API 服务器无法识别的字段，API 服务器会丢弃该字段
+（例如： `PUT` 请求中的 JSON 主体）。
+
+<!--
+There are two situations where the API server drops fields that you supplied in
+an HTTP request.
+-->
+API 服务器会在两种情况下丢弃 HTTP 请求中提供的字段。
+
+<!--
+These situations are:
+-->
+这些情况是：
+
+<!--
+1. The field is unrecognized because it is not in the resource's OpenAPI schema. (One
+   exception to this is for {{< glossary_tooltip
+   term_id="CustomResourceDefinition" text="CRDs" >}} that explicitly choose not to prune unknown
+   fields via `x-kubernetes-preserve-unknown-fields`).
+-->
+1. 相关资源的 OpenAPI 模式定义中没有该字段，因此无法识别该字段（有种例外情形是，
+   {{< glossary_tooltip term_id="CustomResourceDefinition" text="CRD" >}}
+   通过 `x-kubernetes-preserve-unknown-fields` 显式选择不删除未知字段）。
+
+<!--
+1. The field is duplicated in the object.
+-->
+2. 字段在对象中重复出现。
+
+<!--
+### Setting the field validation level
+-->
+### 设置字段校验层级   {#setting-the-field-validation-level}
+
+  {{< feature-state for_k8s_version="v1.25" state="beta" >}}
+
+<!--
+Provided that the `ServerSideFieldValidation` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled (disabled
+by default in 1.23 and 1.24, enabled by default starting in 1.25), you can take
+advantage of server side field validation to catch these unrecognized fields.
+-->
+如果启用了 `ServerSideFieldValidation` [特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)
+（在 1.23 和 1.24 中默认处于禁用状态，从 1.25 开始默认启用），
+你可以用服务端的字段校验来抓取这些未能识别的字段。
+
+<!--
+When you use HTTP verbs that can submit data (`POST`, `PUT`, and `PATCH`), field
+validation gives you the option to choose how you would like to be notified of
+these fields that are being dropped by the API server. Possible levels of
+validation are `Ignore`, `Warn`, and `Strict`.
+-->
+使用可以提交数据的 HTTP 动词（`POST`、`PUT`、`PATCH`）时，可以在字段校验中设置
+API 服务器丢弃字段时的通知设置。通知层级可能包括 `Ignore`、`Warn` 和 `Strict`。
+
+{{< note >}}
+<!--
+If you submit a request that specifies an unrecognized field, and that is also invalid for
+a different reason (for example, the request provides a string value where the API expects
+an integer), then the API server responds with a 400 Bad Request error response.
+You always receive an error response in this case, no matter what field validation level you requested.
+-->
+如果你所提交的请求中指定了无法识别的字段，并且该请求由于其他某种原因无法生效
+（例如：请求提供的是字符值，而 API 需要整数），那么 API 服务器会返回 400 Bad Request（400 请求无效）错误响应码。
+
+在这种情况下，无论请求哪个层级的字段校验，都总会收到错误响应。
+{{< /note >}}
+
+<!--
+Field validation is set by the `fieldValidation` query parameter. The three
+values that you can provide for this parameter are:
+-->
+字段校验需要通过 `fieldValidation` 查询参数进行设置。此参数接受三种值：
+
+<!--
+: 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.
+-->
+`Ignore`
+: 使 API 服务器像没有遇到错误字段一样成功处理请求，丢弃所有的未知字段和重复字段，并且不发送丢弃字段的通知。
+
+<!--
+: (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/).
+-->
+`Warn`
+:（默认值）使 API 服务器成功处理请求，并向客户端发送告警信息。告警信息通过 `Warning:` 响应头发送，
+并为每个未知字段或重复字段添加一条告警信息。有关告警和相关的 Kubernetes API 的信息，
+可参阅博文[告警：增加实用告警功能](/blog/2020/09/03/warnings/)。
+
+<!--
+: 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.
+-->
+`Strict`
+: API 服务器检测到任何未知字段或重复字段时，拒绝处理请求并返回 400 Bad Request 错误。
+来自 API 服务器的响应消息列出了 API 检测到的所有未知字段或重复字段。
+
+<!--
+Tools that submit requests to the server (such as `kubectl`), might set their own
+defaults that are different from the `Warn` validation level that the API server uses
+by default.
+-->
+向服务器提交请求的工具（例如 `kubectl`）可能会设置自己的默认值，与 API 服务器默认使用的 `Warn`
+校验层级不同。
+
+<!--
+The `kubectl` tool uses the `--validate` flag to set the level of field validation.
+Historically `--validate` was used to toggle client-side validation on or off as
+a boolean flag. Since Kubernetes 1.25, kubectl uses
+server-side field validation when sending requests to a serer with this feature
+enabled. Validation will fall back to client-side only when it cannot connect
+to an API server with field validation enabled.
+-->
+`kubectl` 工具使用 `--validate` 标志设置字段校验层级。
+之前 `--validate` 被作为布尔值开启或关闭客户段的校验功能。
+从 Kubernetes 1.25 开始，kubectl 向启用字段校验的服务器发送请求时使用服务端字段校验。
+只有无法连接启用了字段校验的 API 服务器时，才会恢复使用客户端的字段校验。
+<!--
+It accepts the values `ignore`, `warn`,
+and `strict` while also accepting the values `true` (equivalent to `strict`) and `false`
+(equivalent to `ignore`). The default validation setting for kubectl is `--validate=true`,
+which means strict server-side field validation.
+-->
+`kubectl` 接受 `ignore`、`warn`、`strict` 值，同时也接受 `true`（等效于 `strict`）
+和 `false`（等效于 `ignore`）。kubectl 的字段校验默认配置为 `--validate=true`，
+即服务端的 `strict` 级字段校验。
+
 <!--
 ## Dry-run
 -->
@@ -1048,7 +1213,7 @@ request is as close as possible to a non-dry-run response. Kubernetes guarantees
 dry-run requests will not be persisted in storage or have any other side effects.
 -->
 当你使用可以修改资源的 HTTP 动词（`POST`、`PUT`、`PATCH` 和 `DELETE`）时，
-你可以在 _试运行（dry run）_ 模式下提交你的请求。
+你可以在 **试运行（dry run）** 模式下提交你的请求。
 试运行模式有助于通过典型的请求阶段（准入链、验证、合并冲突）评估请求，直到将对象持久化到存储中。
 请求的响应正文尽可能接近非试运行响应。Kubernetes 保证试运行请求不会被持久化存储或产生任何其他副作用。
 
@@ -1130,6 +1295,7 @@ Accept: application/json
 The response would look the same as for non-dry-run request, but the values of some
 generated fields may differ.
 -->
+
 响应会与非试运行模式请求的响应看起来相同，只是某些生成字段的值可能会不同。
 
 <!--
@@ -1179,7 +1345,7 @@ Deployments:
 
 ```yaml
 rules:
-- apiGroups: ["extensions", "apps"]
+- apiGroups: ["apps"]
   resources: ["deployments"]
   verbs: ["patch"]
 ```
@@ -1212,7 +1378,7 @@ Kubernetes 的[服务器端应用](/zh-cn/docs/reference/using-api/server-side-a
 请参阅[服务器端应用](/zh-cn/docs/reference/using-api/server-side-apply/)。
 
 <!--
-## Resource Versions
+## 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
@@ -1325,6 +1491,7 @@ quorum read to be served.
 
 Setting the `resourceVersionMatch` parameter without setting `resourceVersion` is not valid.
 
+
 This table explains the behavior of **list** requests with various combinations of
 `resourceVersion` and `resourceVersionMatch`:
 -->
@@ -1486,7 +1653,7 @@ For watch, the semantics of resource version are:
 -->
 ### **watch** 语义   {#semantics-for-watch}
 
-对于 watch 操作而言，资源版本的语义如下：
+对于 **watch** 操作而言，资源版本的语义如下：
 
 **watch：**