diff --git a/content/zh-cn/docs/reference/access-authn-authz/extensible-admission-controllers.md b/content/zh-cn/docs/reference/access-authn-authz/extensible-admission-controllers.md index 5a3a89c589..09864f59f9 100644 --- a/content/zh-cn/docs/reference/access-authn-authz/extensible-admission-controllers.md +++ b/content/zh-cn/docs/reference/access-authn-authz/extensible-admission-controllers.md @@ -216,7 +216,7 @@ You must replace the `` in the above example by a valid CA bundle which is a PEM-encoded (field value is Base64 encoded) CA bundle for validating the webhook's server certificate. --> 你必须在以上示例中将 `` 替换为一个有效的 CA 证书包， -这是一个用 PEM 编码的（字段值是 Base64 编码） CA 证书包，用于校验 Webhook 的服务器证书。 +这是一个用 PEM 编码的（字段值是 Base64 编码）CA 证书包，用于校验 Webhook 的服务器证书。 {{< /note >}} ```yaml -# 1.17 中被淘汰，推荐使用 apiserver.config.k8s.io/v1 +# 1.17 中被弃用，推荐使用 apiserver.config.k8s.io/v1 apiVersion: apiserver.k8s.io/v1alpha1 kind: AdmissionConfiguration plugins: - name: ValidatingAdmissionWebhook configuration: - # 1.17 中被淘汰，推荐使用 apiserver.config.k8s.io/v1，kind = WebhookAdmissionConfiguration + # 1.17 中被弃用，推荐使用 apiserver.config.k8s.io/v1，kind = WebhookAdmissionConfiguration apiVersion: apiserver.config.k8s.io/v1alpha1 kind: WebhookAdmission kubeConfigFile: "" - name: MutatingAdmissionWebhook configuration: - # 1.17 中被淘汰，推荐使用 apiserver.config.k8s.io/v1，kind = WebhookAdmissionConfiguration + # 1.17 中被弃用，推荐使用 apiserver.config.k8s.io/v1，kind = WebhookAdmissionConfiguration apiVersion: apiserver.config.k8s.io/v1alpha1 kind: WebhookAdmission kubeConfigFile: "" @@ -356,7 +356,7 @@ See the [webhook configuration](#webhook-configuration) section for details abou In the kubeConfig file, provide the credentials: --> 有关 `AdmissionConfiguration` 的更多信息，请参见 -[AdmissionConfiguration (v1) reference](/docs/reference/config-api/apiserver-webhookadmission.v1/)。 +[AdmissionConfiguration (v1) reference](/zh-cn/docs/reference/config-api/apiserver-webhookadmission.v1/)。 有关每个配置字段的详细信息，请参见 [Webhook 配置](#webhook-配置)部分。 在 kubeConfig 文件中，提供证书凭据： @@ -412,7 +412,7 @@ users: apiVersion: v1 kind: Config users: -# 名称应设置为服务的 DNS 名称或配置了 Webhook 的 URL 的主机名（包括端口）。 +# name 应设置为服务的 DNS 名称或配置了 Webhook 的 URL 的主机名（包括端口）。 # 如果将非 443 端口用于服务，则在配置 1.16+ API 服务器时，该端口必须包含在名称中。 # # 对于配置在默认端口（443）上与服务对话的 Webhook，请指定服务的 DNS 名称： @@ -426,16 +426,16 @@ users: # - name: webhook1.ns1.svc # user: ... # -# 对于配置为使用 URL 的 webhook，请匹配在 webhook 的 URL 中指定的主机（和端口）。 -# 带有 `url: https://www.example.com` 的 webhook： +# 对于配置为使用 URL 的 Webhook，请匹配在 Webhook 的 URL 中指定的主机（和端口）。 +# 带有 `url: https://www.example.com` 的 Webhook： # - name: www.example.com # user: ... # -# 带有 `url: https://www.example.com:443` 的 webhook： +# 带有 `url: https://www.example.com:443` 的 Webhook： # - name: www.example.com:443 # user: ... # -# 带有 `url: https://www.example.com:8443` 的 webhook： +# 带有 `url: https://www.example.com:8443` 的 Webhook： # - name: www.example.com:8443 # user: ... # @@ -474,7 +474,6 @@ serialized to JSON as the body. Webhooks can specify what versions of `AdmissionReview` objects they accept with the `admissionReviewVersions` field in their configuration: --> - ### 请求 {#request} Webhook 发送 POST 请求时，请设置 `Content-Type: application/json` 并对 `admission.k8s.io` API @@ -507,12 +506,110 @@ versions the API server knows how to send, attempts to call to the webhook will This example shows the data contained in an `AdmissionReview` object for a request to update the `scale` subresource of an `apps/v1` `Deployment`: --> -API 服务器将发送的是 `admissionReviewVersions` 列表中所支持的第一个 `AdmissionReview` 版本。如果 API 服务器不支持列表中的任何版本，则不允许创建配置。 +API 服务器将发送的是 `admissionReviewVersions` 列表中所支持的第一个 `AdmissionReview` 版本。 +如果 API 服务器不支持列表中的任何版本，则不允许创建配置。 -如果 API 服务器遇到以前创建的 Webhook 配置，并且不支持该 API 服务器知道如何发送的任何 `AdmissionReview` 版本，则调用 Webhook 的尝试将失败，并依据[失败策略](#failure-policy)进行处理。 +如果 API 服务器遇到以前创建的 Webhook 配置，并且不支持该 API 服务器知道如何发送的任何 +`AdmissionReview` 版本，则调用 Webhook 的尝试将失败，并依据[失败策略](#failure-policy)进行处理。 此示例显示了 `AdmissionReview` 对象中包含的数据，该数据用于请求更新 `apps/v1` `Deployment` 的 `scale` 子资源： + ```yaml apiVersion: admission.k8s.io/v1 kind: AdmissionReview @@ -520,13 +617,13 @@ request: # 唯一标识此准入回调的随机 uid uid: 705ab4f5-6393-11e8-b7cc-42010a800002 - # 传入完全正确的 group/version/kind 对象 + # 传入完全限定的 group/version/kind 对象 kind: group: autoscaling version: v1 kind: Scale - # 修改 resource 的完全正确的的 group/version/kind + # 修改 resource 的完全限定 group/version/kind resource: group: apps version: v1 @@ -625,8 +722,6 @@ At a minimum, the `response` stanza must contain the following fields: * `uid`, copied from the `request.uid` sent to the webhook * `allowed`, either set to `true` or `false` - -Example of a minimal response from a webhook to allow a request: --> `response` 至少必须包含以下字段： @@ -782,7 +877,7 @@ If more than 4096 characters of warning messages are added (from all sources), a -## Webhook 配置{#webhook-configuration} +## Webhook 配置 {#webhook-configuration} -### 匹配请求-规则{#matching-requests-rules} +### 匹配请求-规则 {#matching-requests-rules} 通过指定 `objectSelector`，Webhook 能够根据可能发送的对象的标签来限制哪些请求被拦截。 如果指定，则将对 `objectSelector` 和可能发送到 Webhook 的 object 和 oldObject -进行评估。如果两个对象之一与选择器匹配，则认为该请求已匹配。 +进行评估。如果两个对象之一与选择算符匹配，则认为该请求已匹配。 -有关标签选择器的更多示例，请参见[标签](/zh-cn/docs/concepts/overview/working-with-objects/labels)。 +有关标签选择算符的更多示例，请参见[标签的概念](/zh-cn/docs/concepts/overview/working-with-objects/labels)。 -`namespaceSelector` 根据名字空间的标签是否匹配选择器，决定是否针对具名字空间的资源 +`namespaceSelector` 根据名字空间的标签是否匹配选择算符，决定是否针对具名字空间的资源 （或 Namespace 对象）的请求运行 Webhook。 如果对象是除 Namespace 以外的集群范围的资源，则 `namespaceSelector` 标签无效。 @@ -1056,8 +1152,8 @@ webhooks: See [labels concept](/docs/concepts/overview/working-with-objects/labels) for more examples of label selectors. --> -有关标签选择器的更多示例，请参见 -[标签](/zh-cn/docs/concepts/overview/working-with-objects/labels)。 +有关标签选择算符的更多示例， +请参见[标签的概念](/zh-cn/docs/concepts/overview/working-with-objects/labels)。 -- `object` - 来自传入请求的对象。对于 DELETE 请求，该值为 null。 - 该对象版本可能根据 [matchPolicy](#matching-requests-matchpolicy) 进行转换。 - -- `oldObject` - 现有对象。对于 CREATE 请求，该值为 null。 - -- `request` - [AdmissionReview](#request) 的请求部分，不包括 object 和 oldObject。 - -- `authorizer` - 一个 CEL 鉴权组件。可用于对请求的主体（经过身份认证的用户）执行鉴权检查。 - 更多详细信息，请参阅 Kubernetes CEL 库文档中的 - [Authz](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz)。 - +- `object` - 来自传入请求的对象。对于 DELETE 请求，该值为 null。 + 该对象版本可能根据 [matchPolicy](#matching-requests-matchpolicy) 进行转换。 +- `oldObject` - 现有对象。对于 CREATE 请求，该值为 null。 +- `request` - [AdmissionReview](#request) 的请求部分，不包括 object 和 oldObject。 +- `authorizer` - 一个 CEL 鉴权组件。可用于对请求的主体（经过身份认证的用户）执行鉴权检查。 + 更多详细信息，请参阅 Kubernetes CEL 库文档中的 + [Authz](https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz)。 - `authorizer.requestResource` - 对配置的请求资源（组、资源、（子资源）、名字空间、名称）进行授权检查的快捷方式。 -1. 如果**任何一个**匹配条件求值结果为 `false`（不管其他错误），API 服务器将跳过 Webhook。 - -1. 否则： +1. 如果**任何一个**匹配条件求值结果为 `false`（不管其他错误），API 服务器将跳过 Webhook。 +2. 否则： - 对于 [`failurePolicy: Fail`](#failure-policy)，拒绝请求（不调用 Webhook）。 - 对于 [`failurePolicy: Ignore`](#failure-policy)，继续处理请求但跳过 Webhook。 @@ -1370,10 +1457,7 @@ API 服务器确定请求应发送到 Webhook 后，它需要知道如何调用 Webhook 可以通过 URL 或服务引用来调用，并且可以选择包含自定义 CA 包，以用于验证 TLS 连接。 - -#### URL{#url} -使用用户或基本身份验证（例如："user:password@"）是不允许的。 -使用片段（"#..."）和查询参数（"?..."）也是不允许的。 +使用用户或基本身份验证（例如：`user:password@`）是不允许的。 +使用片段（`#...`）和查询参数（`?...`）也是不允许的。 -### 副作用{#side-effects} +### 副作用 {#side-effects} -进行带外更改的（产生“副作用”的） Webhook 必须具有协调机制（如控制器）， +进行带外更改的（产生“副作用”的）Webhook 必须具有协调机制（如控制器）， 该机制定期确定事物的实际状态，并调整由准入 Webhook 修改的带外数据以反映现实情况。 这是因为对准入 Webhook 的调用不能保证所准入的对象将原样保留，或根本不保留。 以后，Webhook 可以修改对象的内容，在写入存储时可能会发生冲突， @@ -1531,7 +1615,7 @@ Webhook 使用 Webhook 配置中的 `sideEffects` 字段显示它们是否有副 -这是一个 validating Webhook 的示例，表明它对 `dryRun: true` 请求没有副作用： +这是一个验证性质的 Webhook 的示例，表明它对 `dryRun: true` 请求没有副作用： ```yaml apiVersion: admissionregistration.k8s.io/v1 @@ -1544,7 +1628,7 @@ webhooks: -### 超时{#timeouts} +### 超时 {#timeouts} -变更性质的 Webhook 必须具有[幂等](#idempotence)性， +变更性质的 Webhook 必须具有[幂等性](#idempotence)， 并且能够成功处理已被接纳并可能被修改的对象的变更性质的 Webhook。 对于所有变更性质的准入 Webhook 都是如此， 因为它们可以在对象中进行的任何更改可能已经存在于用户提供的对象中，但是对于选择重新调用的 Webhook @@ -1724,7 +1808,7 @@ API 服务器提供了监视准入 Webhook 行为的方法。这些监视机制 -### Mutating Webhook 审计注解 {#mutating-webhook-auditing-annotations} +### 变更性质的 Webhook 审计注解 {#mutating-webhook-auditing-annotations} + 例如，对于正在被重新调用的某 Webhook，所记录的注解如下。 Webhook 在 mutating Webhook 链中排在第三个位置，并且在调用期间未改变请求对象。 + + ```yaml # 审计事件相关记录 { @@ -1784,6 +1885,17 @@ The audit level of a event determines which annotations get recorded: } ``` + + ```yaml # 反序列化的注解值 { @@ -1798,8 +1910,26 @@ The audit level of a event determines which annotations get recorded: is ordered the first in the mutating webhook chain, and mutated the request object during the invocation. --> + 对于在第一轮中调用的 Webhook，所记录的注解如下。 - Webhook 在 mutating Webhook 链中排在第一位，并在调用期间改变了请求对象。 + Webhook 在变更性质的 Webhook 链中排在第一位，并在调用期间改变了请求对象。 + + ```yaml # 审计事件相关记录 @@ -1816,6 +1946,17 @@ The audit level of a event determines which annotations get recorded: } ``` + + ```yaml # 反序列化的注解值 { @@ -1842,6 +1983,23 @@ The audit level of a event determines which annotations get recorded: Webhook 在变更性质的 Webhook 链中排在第四，并在其响应中包含一个 JSON 补丁， 该补丁已被应用于请求对象。 + + ```yaml # 审计事件相关记录 { @@ -1857,6 +2015,24 @@ The audit level of a event determines which annotations get recorded: } ``` + + ```yaml # 反序列化的注解值 { @@ -1981,7 +2157,7 @@ In the cases above, the webhook can be safely reinvoked, or admit an object that 设置为 true，以实施安全最佳实践。 2. 对于 `CREATE` Pod 请求，如果未设置容器的字段 `.spec.containers[].resources.limits`，设置默认资源限制值。 -3. 对于 `CREATE` pod 请求，如果 Pod 中不存在名为 `foo-sidecar` 的边车容器， +3. 对于 `CREATE` Pod 请求，如果 Pod 中不存在名为 `foo-sidecar` 的边车容器， 向 Pod 注入一个 `foo-sidecar` 容器。 在上述情况下，可以安全地重新调用 Webhook，或接受已经设置了字段的对象。 @@ -2002,11 +2178,11 @@ In the cases above, the webhook can be safely reinvoked, or admit an object that `foo-sidecar` without looking to see if there is already a `foo-sidecar` container in the pod. --> -1. 对于 `CREATE` pod 请求，注入名称为 `foo-sidecar` 并带有当前时间戳的 - 边车容器（例如 `foo-sidecar-19700101-000000`）。 -2. 对于 `CREATE/UPDATE` pod 请求，如果容器已设置标签 `"env"` 则拒绝， +1. 对于 `CREATE` Pod 请求，注入名称为 `foo-sidecar` + 并带有当前时间戳的边车容器（例如 `foo-sidecar-19700101-000000`）。 +2. 对于 `CREATE/UPDATE` Pod 请求，如果容器已设置标签 `"env"` 则拒绝， 否则将 `"env": "prod"` 标签添加到容器。 -3. 对于 `CREATE` pod 请求，盲目地添加一个名为 `foo-sidecar` 的边车容器， +3. 对于 `CREATE` Pod 请求，盲目地添加一个名为 `foo-sidecar` 的边车容器， 而未查看 Pod 中是否已经有 `foo-sidecar` 容器。 -在上述第一种情况下，重新调用该 Webhook 可能导致同一个 Sidecar 容器 -多次注入到 Pod 中，而且每次使用不同的容器名称。 +在上述第一种情况下，重新调用该 Webhook 可能导致同一个边车容器多次注入到 +Pod 中，而且每次使用不同的容器名称。 类似地，如果 Sidecar 已存在于用户提供的 Pod 中，则 Webhook 可能注入重复的容器。 在上述第二种情况下，重新调用 Webhook 将导致 Webhook 自身输出失败。 -在上述第三种情况下，重新调用 Webhook 将导致 Pod 规范中的容器重复， +在上述第三种情况下，重新调用 Webhook 将导致 Pod 规约中的容器重复， 从而使请求无效并被 API 服务器拒绝。