Merge pull request #41324 from windsonsea/cely

[zh] sync /using-api/cel.md and api-concepts.md

Author: k8s-ci-robot

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

@@ -82,7 +82,7 @@ as a permission check
 -->
 大多数 Kubernetes API
 资源类型都是[对象](/zh-cn/docs/concepts/overview/working-with-objects/kubernetes-objects/#kubernetes-objects)：
-它们代表集群上某个概念的具体实例，例如 Pod 或命名空间。
+它们代表集群上某个概念的具体实例，例如 Pod 或名字空间。
 少数 API 资源类型是 “虚拟的”，它们通常代表的是操作而非对象本身，
 例如权限检查（使用带有 JSON 编码的 `SubjectAccessReview` 主体的 POST 到 `subjectaccessreviews` 资源），
 或 Pod 的子资源 `eviction`（用于触发 [API-发起的驱逐](/zh-cn/docs/concepts/scheduling-eviction/api-eviction/)）。
@@ -105,10 +105,10 @@ example: Nodes), and so their names must be unique across the whole cluster.
 你可以通过 API 创建的所有对象都有一个唯一的{{< glossary_tooltip text="名字" term_id="name" >}}，
 以允许幂等创建和检索，
 但如果虚拟资源类型不可检索或不依赖幂等性，则它们可能没有唯一名称。
-在{{< glossary_tooltip text="命名空间" term_id="namespace" >}}内，
+在{{< glossary_tooltip text="名字空间" term_id="namespace" >}}内，
 同一时刻只能有一个给定类别的对象具有给定名称。
 但是，如果你删除该对象，你可以创建一个具有相同名称的新对象。
-有些对象没有命名空间（例如：节点），因此它们的名称在整个集群中必须是唯一的。
+有些对象没有名字空间（例如：节点），因此它们的名称在整个集群中必须是唯一的。
 
 <!--
 ### API verbs
@@ -236,7 +236,7 @@ Kubernetes API 允许客户端对对象或集合发出初始请求，然后跟
 客户端可以发送 **list** 或者 **get** 请求，然后发出后续 **watch** 请求。
 
 为了使这种更改跟踪成为可能，每个 Kubernetes 对象都有一个 `resourceVersion` 字段，
-表示存储在底层持久层中的该资源的版本。在检索资源集合（命名空间或集群范围）时，
+表示存储在底层持久层中的该资源的版本。在检索资源集合（名字空间或集群范围）时，
 来自 API 服务器的响应包含一个 `resourceVersion` 值。
 客户端可以使用该 `resourceVersion` 来启动对 API 服务器的 **watch**。
 
@@ -255,7 +255,8 @@ for more detail.
 For example:
 -->
 当你发送 **watch** 请求时，API 服务器会响应更改流。
-这些更改逐项列出了在你指定为 **watch** 请求参数的 `resourceVersion` 之后发生的操作（例如 **create**、**delete** 和 **update**）的结果。
+这些更改逐项列出了在你指定为 **watch** 请求参数的 `resourceVersion` 之后发生的操作
+（例如 **create**、**delete** 和 **update**）的结果。
 整个 **watch** 机制允许客户端获取当前状态，然后订阅后续更改，而不会丢失任何事件。
 
 如果客户端 **watch** 连接断开，则该客户端可以从最后返回的 `resourceVersion` 开始新的 **watch** 请求；
@@ -288,12 +289,12 @@ For example:
    _test_ namespace. Each change notification is a JSON document. The HTTP response body
    (served as `application/json`) consists a series of JSON documents.
 -->
-2. 从资源版本 10245 开始，接收影响 _test_ 命名空间中 Pod 的所有 API 操作
+2. 从资源版本 10245 开始，接收影响 _test_ 名字空间中 Pod 的所有 API 操作
    （例如 **create**、**delete**、**apply** 或 **update**）的通知。
    每个更改通知都是一个 JSON 文档。
    HTTP 响应正文（用作 `application/json`）由一系列 JSON 文档组成。
 
-   ```
+   ```console
    GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
    ---
    200 OK
@@ -444,6 +445,7 @@ in the following sequence of events:
 举个例子：你想监视一组 Pod。对于该集合，当前资源版本为 10245，并且有两个 Pod：`foo` 和 `bar`。
 接下来你发送了以下请求（通过使用 `resourceVersion=` 设置空的资源版本来明确请求 **一致性读**），
 这样做的结果是可能收到如下事件序列：
+
 ```console
 GET /api/v1/namespaces/test/pods?watch=1&sendInitialEvents=true&allowWatchBookmarks=true&resourceVersion=&resourceVersionMatch=NotOlderThan
 ---
@@ -483,7 +485,7 @@ response (10-20MB) and consume a large amount of server resources.
 -->
 在较大规模集群中，检索某些资源类型的集合可能会导致非常大的响应，从而影响服务器和客户端。
 例如，一个集群可能有数万个 Pod，每个 Pod 大约相当于 2 KiB 的编码 JSON。
-跨所有命名空间检索所有 Pod 可能会导致非常大的响应 (10-20MB) 并消耗大量服务器资源。
+跨所有名字空间检索所有 Pod 可能会导致非常大的响应 (10-20MB) 并消耗大量服务器资源。
 
 <!--
 Provided that you don't explicitly disable the `APIListChunking`

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

@@ -188,6 +188,10 @@ Examples:
 | `lowPriorities.map(x, x.priority).max() < highPriorities.map(x, x.priority).min()` | 验证两组优先级不重叠                 |
 | `names.indexOf('should-be-first') == 1`                                            | 如果是特定值，则使用列表中的第一个名称  |
 
+<!--
+See the [Kubernetes List Library](https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apiserver/schema/cel/library#Lists)
+godoc for more information.
+-->
 更多信息请查阅 Go 文档：
 [Kubernetes 列表库](https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apiserver/schema/cel/library#Lists)。
 {{< /table >}}
@@ -283,6 +287,85 @@ godoc for more information.
 更多信息请查阅 Go 文档：
 [Kubernetes URL 库](https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apiserver/schema/cel/library#URLs)。
 
+<!--
+### Kubernetes authorizer library
+
+For CEL expressions in the API where a variable of type `Authorizer` is available,
+the authorizer may be used to perform authorization checks for the principal
+(authenticated user) of the request.
+
+API resource checks are performed as follows:
+-->
+### Kubernetes 鉴权组件库
+
+在 API 中使用 CEL 表达式，可以使用类型为 `Authorizer` 的变量，
+这个鉴权组件可用于对请求的主体（已认证用户）执行鉴权检查。
+
+API 资源检查的过程如下：
+
+<!--
+1. Specify the group and resource to check: `Authorizer.group(string).resource(string) ResourceCheck`
+2. Optionally call any combination of the following builder functions to further narrow the authorization check.
+   Note that these functions return the receiver type and can be chained:
+  - `ResourceCheck.subresource(string) ResourceCheck`
+  - `ResourceCheck.namespace(string) ResourceCheck`
+  - `ResourceCheck.name(string) ResourceCheck` 
+3. Call `ResourceCheck.check(verb string) Decision` to perform the authorization check.
+4. Call `allowed() bool` or `reason() string` to inspect the result of the authorization check.
+-->
+1. 指定要检查的组和资源：`Authorizer.group(string).resource(string) ResourceCheck`
+2. 可以调用以下任意组合的构建器函数（Builder Function），以进一步缩小鉴权检查范围。
+   注意这些函数将返回接收者的类型，并且可以串接起来：
+   - `ResourceCheck.subresource(string) ResourceCheck`
+   - `ResourceCheck.namespace(string) ResourceCheck`
+   - `ResourceCheck.name(string) ResourceCheck` 
+3. 调用 `ResourceCheck.check(verb string) Decision` 来执行鉴权检查。
+4. 调用 `allowed() bool` 或 `reason() string` 来查验鉴权检查的结果。
+
+<!--
+Non-resource authorization performed are used as follows:
+
+1. specify only a path: `Authorizer.path(string) PathCheck`
+1. Call `PathCheck.check(httpVerb string) Decision` to perform the authorization check.
+1. Call `allowed() bool` or `reason() string` to inspect the result of the authorization check.
+-->
+对非资源访问的鉴权过程如下：
+
+1. 仅指定路径：`Authorizer.path(string) PathCheck`
+1. 调用 `PathCheck.check(httpVerb string) Decision` 来执行鉴权检查。
+1. 调用 `allowed() bool` 或 `reason() string` 来查验鉴权检查的结果。
+
+<!--
+To perform an authorization check for a service account:
+-->
+对于服务账号执行鉴权检查的方式：
+
+- `Authorizer.serviceAccount(namespace string, name string) Authorizer`
+
+<!--
+{{< table caption="Examples of CEL expressions using URL library functions" >}}
+| CEL Expression                                                                                               | Purpose                                        |
+|--------------------------------------------------------------------------------------------------------------|------------------------------------------------|
+| `authorizer.group('').resource('pods').namespace('default').check('create').allowed()`                       | Returns true if the principal (user or service account) is allowed create pods in the 'default' namespace. |
+| `authorizer.path('/healthz').check('get').allowed()`                                                         | Checks if the principal (user or service account) is authorized to make HTTP GET requests to the /healthz API path. |
+| `authorizer.serviceAccount('default', 'myserviceaccount').resource('deployments').check('delete').allowed()` | Checks if the service account is authorized to delete deployments. |
+{{< /table >}}
+-->
+{{< table caption="使用 URL 库函数的 CEL 表达式示例" >}}
+| CEL 表达式                                       | 用途                                           |
+|-------------------------------------------------|------------------------------------------------|
+| `authorizer.group('').resource('pods').namespace('default').check('create').allowed()`  | 如果主体（用户或服务账号）被允许在 `default` 名字空间中创建 Pod，返回 true。 |
+| `authorizer.path('/healthz').check('get').allowed()`   | 检查主体（用户或服务账号）是否有权限向 /healthz API 路径发出 HTTP GET 请求。 |
+| `authorizer.serviceAccount('default', 'myserviceaccount').resource('deployments').check('delete').allowed()` | 检查服务账号是否有权限删除 Deployment。 |
+{{< /table >}}
+
+<!--
+See the [Kubernetes Authz library](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz)
+godoc for more information.
+-->
+更多信息请参阅 Go 文档：
+[Kubernetes Authz library](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz)。
+
 <!--
 ## Type checking
 
@@ -391,7 +474,7 @@ Also see: [CEL types](https://github.com/google/cel-spec/blob/v0.6.0/doc/langdef
 -->
 另见：[CEL 类型](https://github.com/google/cel-spec/blob/v0.6.0/doc/langdef.md#values)、
 [OpenAPI 类型](https://swagger.io/specification/#data-types)、
-[Kubernetes 结构化模式](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema)。
+[Kubernetes 结构化模式](/zh-cn/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema)。
 
 <!--
 Equality comparison for arrays with `x-kubernetes-list-type` of `set` or `map` ignores element