From b672cea482f2546ccaadb13ab01ff4ae9eeeedd7 Mon Sep 17 00:00:00 2001 From: Zhuzhenghao Date: Thu, 13 Apr 2023 15:27:13 +0800 Subject: [PATCH] [zh] resync page extensible-admission-controllers --- .../extensible-admission-controllers.md | 424 ++++++++++-------- 1 file changed, 233 insertions(+), 191 deletions(-) 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 7b29c76a347..7beaa90ee91 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 @@ -3,8 +3,14 @@ title: 动态准入控制 content_type: concept weight: 40 --- - + @@ -29,16 +36,16 @@ This page describes how to build, configure, use, and monitor admission webhooks 准入 Webhook 是一种用于接收准入请求并对其进行处理的 HTTP 回调机制。 可以定义两种类型的准入 webhook，即 [验证性质的准入 Webhook](/zh-cn/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook) 和 [修改性质的准入 Webhook](/zh-cn/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook)。 -修改性质的准入 Webhook 会先被调用。它们可以更改发送到 API +修改性质的准入 Webhook 会先被调用。它们可以更改发送到 API 服务器的对象以执行自定义的设置默认值操作。 -{{< note >}} 如果准入 Webhook 需要保证它们所看到的是对象的最终状态以实施某种策略。 则应使用验证性质的准入 Webhook，因为对象被修改性质 Webhook 看到之后仍然可能被修改。 {{< /note >}} -### 尝试准入 Webhook {#experimenting-with-admission-webhooks} +## 尝试准入 Webhook {#experimenting-with-admission-webhooks} 准入 Webhook 本质上是集群控制平面的一部分。你应该非常谨慎地编写和部署它们。 如果你打算编写或者部署生产级准入 webhook，请阅读[用户指南](/zh-cn/docs/reference/access-authn-authz/extensible-admission-controllers/#write-an-admission-webhook-server)以获取相关说明。 @@ -101,19 +109,19 @@ that is validated in a Kubernetes e2e test. The webhook handles the as an `AdmissionReview` object in the same version it received. --> 请参阅 Kubernetes e2e 测试中的 -[admission webhook 服务器](https://github.com/kubernetes/kubernetes/blob/release-1.21/test/images/agnhost/webhook/main.go) +[Admission Webhook 服务器](https://github.com/kubernetes/kubernetes/blob/release-1.21/test/images/agnhost/webhook/main.go) 的实现。webhook 处理由 API 服务器发送的 `AdmissionReview` 请求，并且将其决定 作为 `AdmissionReview` 对象以相同版本发送回去。 -有关发送到 webhook 的数据的详细信息，请参阅 [webhook 请求](#request)。 +有关发送到 Webhook 的数据的详细信息，请参阅 [Webhook 请求](#request)。 -要获取来自 webhook 的预期数据，请参阅 [webhook 响应](#response)。 +要获取来自 Webhook 的预期数据，请参阅 [Webhook 响应](#response)。 示例准入 Webhook 服务器置 `ClientAuth` 字段为 [空](https://github.com/kubernetes/kubernetes/blob/v1.22.0/test/images/agnhost/webhook/config.go#L38-L39)， -默认为 `NoClientCert` 。这意味着 webhook 服务器不会验证客户端的身份，认为其是 apiservers。 +默认为 `NoClientCert` 。这意味着 Webhook 服务器不会验证客户端的身份，认为其是 apiservers。 如果你需要双向 TLS 或其他方式来验证客户端，请参阅 如何[对 apiservers 进行身份认证](#authenticate-apiservers)。 @@ -141,18 +149,18 @@ The test also creates a [service](/docs/reference/generated/kubernetes-api/{{< p as the front-end of the webhook server. See [code](https://github.com/kubernetes/kubernetes/blob/v1.22.0/test/e2e/apimachinery/webhook.go#L748). --> -e2e 测试中的 webhook 服务器通过 +e2e 测试中的 Webhook 服务器通过 [deployment API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#deployment-v1-apps) 部署在 Kubernetes 集群中。该测试还将创建一个 [service](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core) -作为 webhook 服务器的前端。参见 +作为 Webhook 服务器的前端。参见 [相关代码](https://github.com/kubernetes/kubernetes/blob/v1.22.0/test/e2e/apimachinery/webhook.go#L748)。 -你也可以在集群外部署 webhook。这样做需要相应地更新你的 webhook 配置。 +你也可以在集群外部署 Webhook。这样做需要相应地更新你的 Webhook 配置。 -你可以通过 +你可以通过 [ValidatingWebhookConfiguration](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#validatingwebhookconfiguration-v1-admissionregistration-k8s-io) -或者 +或者 [MutatingWebhookConfiguration](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#mutatingwebhookconfiguration-v1-admissionregistration-k8s-io) 动态配置哪些资源要被哪些准入 Webhook 处理。 + -以下是一个 `ValidatingWebhookConfiguration` 示例，mutating webhook 配置与此类似。有关每个配置字段的详细信息，请参阅 [webhook 配置](#webhook-configuration) 部分。 +以下是一个 `ValidatingWebhookConfiguration` 示例，Mutating Webhook 配置与此类似。有关每个配置字段的详细信息，请参阅 [Webhook 配置](#webhook-configuration) 部分。 ```yaml apiVersion: admissionregistration.k8s.io/v1 @@ -184,11 +193,11 @@ metadata: webhooks: - name: "pod-policy.example.com" rules: - - apiGroups: [""] + - apiGroups: [""] apiVersions: ["v1"] - operations: ["CREATE"] - resources: ["pods"] - scope: "Namespaced" + operations: ["CREATE"] + resources: ["pods"] + scope: "Namespaced" clientConfig: service: namespace: "example-namespace" @@ -198,6 +207,7 @@ webhooks: sideEffects: None timeoutSeconds: 5 ``` + {{< note >}} `scope` 字段指定是仅集群范围的资源（Cluster）还是名字空间范围的资源资源（Namespaced）将与此规则匹配。 `*` 表示没有范围限制。 +{{< note >}} -{{< note >}} 当使用 `clientConfig.service` 时，服务器证书必须对 `..svc` 有效。 {{< /note >}} +{{< note >}} -{{< note >}} -Webhook 调用的默认超时是 10 秒，你可以设置 `timeout` 并建议对 webhook 设置较短的超时时间。 -如果 webhook 调用超时，则根据 webhook 的失败策略处理请求。 +Webhook 调用的默认超时是 10 秒，你可以设置 `timeout` 并建议对 Webhook 设置较短的超时时间。 +如果 Webhook 调用超时，则根据 Webhook 的失败策略处理请求。 {{< /note >}} 当一个 API 服务器收到与 `rules` 相匹配的请求时， -该 API 服务器将按照 `clientConfig` 中指定的方式向 webhook 发送一个 `admissionReview` 请求。 +该 API 服务器将按照 `clientConfig` 中指定的方式向 Webhook 发送一个 `admissionReview` 请求。 创建 Webhook 配置后，系统将花费几秒钟使新配置生效。 ### 对 API 服务器进行身份认证 {#authenticate-apiservers} @@ -322,71 +332,74 @@ For more information about `AdmissionConfiguration`, see the [AdmissionConfiguration (v1) reference](/docs/reference/config-api/apiserver-webhookadmission.v1/). See the [webhook configuration](#webhook-configuration) section for details about each config field. -* In the kubeConfig file, provide the credentials: +In the kubeConfig file, provide the credentials: --> 有关 `AdmissionConfiguration` 的更多信息，请参见 [AdmissionConfiguration (v1) reference](/docs/reference/config-api/apiserver-webhookadmission.v1/)。 -有关每个配置字段的详细信息，请参见 [webhook 配置](#webhook-配置)部分。 +有关每个配置字段的详细信息，请参见 [Webhook 配置](#webhook-配置)部分。 -* 在 kubeConfig 文件中，提供证书凭据： +在 kubeConfig 文件中，提供证书凭据： + +```yaml +apiVersion: v1 +kind: Config +users: +# 名称应设置为服务的 DNS 名称或配置了 Webhook 的 URL 的主机名（包括端口）。 +# 如果将非 443 端口用于服务，则在配置 1.16+ API 服务器时，该端口必须包含在名称中。 +# +# 对于配置在默认端口（443）上与服务对话的 Webhook，请指定服务的 DNS 名称： +# - name: webhook1.ns1.svc +# user: ... +# +# 对于配置在非默认端口（例如 8443）上与服务对话的 Webhook，请在 1.16+ 中指定服务的 DNS 名称和端口： +# - name: webhook1.ns1.svc:8443 +# user: ... +# 并可以选择仅使用服务的 DNS 名称来创建第二节，以与 1.15 API 服务器版本兼容： +# - name: webhook1.ns1.svc +# user: ... +# +# 对于配置为使用 URL 的 webhook，请匹配在 webhook 的 URL 中指定的主机（和端口）。 +# 带有 `url: https://www.example.com` 的 webhook： +# - name: www.example.com +# user: ... +# +# 带有 `url: https://www.example.com:443` 的 webhook： +# - name: www.example.com:443 +# user: ... +# +# 带有 `url: https://www.example.com:8443` 的 webhook： +# - name: www.example.com:8443 +# user: ... +# +- name: 'webhook1.ns1.svc' + user: + client-certificate-data: "" + client-key-data: "" +# `name` 支持使用 * 通配符匹配前缀段。 +- name: '*.webhook-company.org' + user: + password: "" + username: "" +# '*' 是默认匹配项。 +- name: '*' + user: + token: "" +``` - ```yaml - apiVersion: v1 - kind: Config - users: - # 名称应设置为服务的 DNS 名称或配置了 Webhook 的 URL 的主机名（包括端口）。 - # 如果将非 443 端口用于服务，则在配置 1.16+ API 服务器时，该端口必须包含在名称中。 - # - # 对于配置在默认端口（443）上与服务对话的 Webhook，请指定服务的 DNS 名称： - # - name: webhook1.ns1.svc - # user: ... - # - # 对于配置在非默认端口（例如 8443）上与服务对话的 Webhook，请在 1.16+ 中指定服务的 DNS 名称和端口： - # - name: webhook1.ns1.svc:8443 - # user: ... - # 并可以选择仅使用服务的 DNS 名称来创建第二节，以与 1.15 API 服务器版本兼容： - # - name: webhook1.ns1.svc - # user: ... - # - # 对于配置为使用 URL 的 webhook，请匹配在 webhook 的 URL 中指定的主机（和端口）。 - # 带有 `url: https://www.example.com` 的 webhook： - # - name: www.example.com - # user: ... - # - # 带有 `url: https://www.example.com:443` 的 webhook： - # - name: www.example.com:443 - # user: ... - # - # 带有 `url: https://www.example.com:8443` 的 webhook： - # - name: www.example.com:8443 - # user: ... - # - - name: 'webhook1.ns1.svc' - user: - client-certificate-data: "" - client-key-data: "" - # `name` 支持使用 * 通配符匹配前缀段。 - - name: '*.webhook-company.org' - user: - password: "" - username: "" - # '*' 是默认匹配项。 - - name: '*' - user: - token: "" - ``` 当然，你需要设置 Webhook 服务器来处理这些身份验证请求。 - + ## Webhook 请求与响应 {#webhook-request-and-response} -创建 webhook 配置时，`admissionReviewVersions` 是必填字段。 +创建 Webhook 配置时，`admissionReviewVersions` 是必填字段。 Webhook 必须支持至少一个当前和以前的 API 服务器都可以解析的 `AdmissionReview` 版本。 当拒绝请求时，Webhook 可以使用 `status` 字段自定义 http 响应码和返回给用户的消息。 @@ -624,7 +639,8 @@ For `patchType: JSONPatch`, the `patch` field contains a base64-encoded array of 对于 `patchType: JSONPatch`，`patch` 字段包含一个以 base64 编码的 JSON patch 操作数组。 @@ -652,18 +668,19 @@ So a webhook response to add that label would be: } ``` - 准入 Webhook 可以选择性地返回在 HTTP `Warning` 头中返回给请求客户端的警告消息，警告代码为 299。 警告可以与允许或拒绝的准入响应一起发送。 - 如果你正在实现返回一条警告的 webhook，则： @@ -674,7 +691,7 @@ If you're implementing a webhook that returns a warning: {{< caution >}} 超过 256 个字符的单条警告消息在返回给客户之前可能会被 API 服务器截断。 如果超过 4096 个字符的警告消息（来自所有来源），则额外的警告消息会被忽略。 @@ -731,37 +748,44 @@ Webhook，则应为每个 Webhook 赋予一个唯一的名称。 Each webhook must specify a list of rules used to determine if a request to the API server should be sent to the webhook. Each rule specifies one or more operations, apiGroups, apiVersions, and resources, and a resource scope: --> -每个 webhook 必须指定用于确定是否应将对 apiserver 的请求发送到 webhook 的规则列表。 +每个 Webhook 必须指定用于确定是否应将对 apiserver 的请求发送到 webhook 的规则列表。 每个规则都指定一个或多个 operations、apiGroups、apiVersions 和 resources 以及资源的 scope： * `operations` 列出一个或多个要匹配的操作。 可以是 `CREATE`、`UPDATE`、`DELETE`、`CONNECT` 或 `*` 以匹配所有内容。 * `apiGroups` 列出了一个或多个要匹配的 API 组。`""` 是核心 API 组。`"*"` 匹配所有 API 组。 * `apiVersions` 列出了一个或多个要匹配的 API 版本。`"*"` 匹配所有 API 版本。 * `resources` 列出了一个或多个要匹配的资源。 - * `"*"` 匹配所有资源，但不包括子资源。 - * `"*/*"` 匹配所有资源，包括子资源。 - * `"pods/*"` 匹配 pod 的所有子资源。 - * `"*/status"` 匹配所有 status 子资源。 + + * `"*"` 匹配所有资源，但不包括子资源。 + * `"*/*"` 匹配所有资源，包括子资源。 + * `"pods/*"` 匹配 pod 的所有子资源。 + * `"*/status"` 匹配所有 status 子资源。 * `scope` 指定要匹配的范围。有效值为 `"Cluster"`、`"Namespaced"` 和 `"*"`。 子资源匹配其父资源的范围。默认值为 `"*"`。 - * `"Cluster"` 表示只有集群作用域的资源才能匹配此规则（API 对象 Namespace 是集群作用域的）。 - * `"Namespaced"` 意味着仅具有名字空间的资源才符合此规则。 - * `"*"` 表示没有作用域限制。 + + * `"Cluster"` 表示只有集群作用域的资源才能匹配此规则（API 对象 Namespace 是集群作用域的）。 + * `"Namespaced"` 意味着仅具有名字空间的资源才符合此规则。 + * `"*"` 表示没有作用域限制。 -仅当选择使用 webhook 时才使用对象选择器，因为最终用户可以通过设置标签来 +仅当选择使用 Webhook 时才使用对象选择器，因为最终用户可以通过设置标签来 跳过准入 Webhook。 此示例显示了一个验证性质的 Webhook，它将匹配到对某名字空间中的任何具名字空间的资源的 `CREATE` 请求，前提是该名字空间具有值为 "prod" 或 "staging" 的 "environment" 标签： @@ -951,7 +976,7 @@ webhooks: matchExpressions: - key: environment operator: In - values: ["prod","staging"] + values: ["prod", "staging"] rules: - operations: ["CREATE"] apiGroups: ["*"] @@ -983,7 +1008,7 @@ For example, if a webhook only specified a rule for some API groups/versions and a request was made to modify the resource via another API group/version (like `extensions/v1beta1`), the request would not be sent to the webhook. --> -例如，如果一个 webhook 仅为某些 API 组/版本指定了规则（例如 +例如，如果一个 Webhook 仅为某些 API 组/版本指定了规则（例如 `apiGroups:["apps"], apiVersions:["v1","v1beta1"]`），而修改资源的请求是通过另一个 API 组/版本（例如 `extensions/v1beta1`）发出的，该请求将不会被发送到 Webhook。 @@ -991,25 +1016,28 @@ API 组/版本（例如 `extensions/v1beta1`）发出的，该请求将不会被 The `matchPolicy` lets a webhook define how its `rules` are used to match incoming requests. Allowed values are `Exact` or `Equivalent`. --> -`matchPolicy` 允许 webhook 定义如何使用其 `rules` 匹配传入的请求。 +`matchPolicy` 允许 Webhook 定义如何使用其 `rules` 匹配传入的请求。 允许的值为 `Exact` 或 `Equivalent`。 * `Exact` 表示仅当请求与指定规则完全匹配时才应拦截该请求。 * `Equivalent` 表示如果某个请求意在修改 `rules` 中列出的资源， 即使该请求是通过其他 API 组或版本发起，也应拦截该请求。 -在上面给出的示例中，仅为 `apps/v1` 注册的 webhook 可以使用 `matchPolicy`： +在上面给出的示例中，仅为 `apps/v1` 注册的 Webhook 可以使用 `matchPolicy`： * `matchPolicy: Exact` 表示不会将 `extensions/v1beta1` 请求发送到 Webhook -* `matchPolicy:Equivalent` 表示将 `extensions/v1beta1` 请求发送到 webhook - （将对象转换为 webhook 指定的版本：`apps/v1`） +* `matchPolicy:Equivalent` 表示将 `extensions/v1beta1` 请求发送到 Webhook + （将对象转换为 Webhook 指定的版本：`apps/v1`） 准入 Webhook 所用的 `matchPolicy` 默认为 `Equivalent`。 @@ -1144,7 +1173,7 @@ webhooks: expression: '!authorizer.group("admissionregistration.k8s.io").resource("validatingwebhookconfigurations").name("my-webhook.example.com").check("breakglass").allowed()' ``` - 匹配条件可以访问以下 CEL 变量： @@ -1217,8 +1246,8 @@ stanza of the webhook configuration. Webhooks can either be called via a URL or a service reference, and can optionally include a custom CA bundle to use to verify the TLS connection. --> -API 服务器确定请求应发送到 webhook 后，它需要知道如何调用 webhook。 -此信息在 webhook 配置的 `clientConfig` 节中指定。 +API 服务器确定请求应发送到 Webhook 后，它需要知道如何调用 webhook。 +此信息在 Webhook 配置的 `clientConfig` 节中指定。 Webhook 可以通过 URL 或服务引用来调用，并且可以选择包含自定义 CA 包，以用于验证 TLS 连接。 @@ -1231,7 +1260,7 @@ Webhook 可以通过 URL 或服务引用来调用，并且可以选择包含自 `url` gives the location of the webhook, in standard URL form (`scheme://host:port/path`). --> -`url` 以标准 URL 形式给出 webhook 的位置（`scheme://host:port/path`）。 +`url` 以标准 URL 形式给出 Webhook 的位置（`scheme://host:port/path`）。 请注意，将 `localhost` 或 `127.0.0.1` 用作 `host` 是有风险的， -除非你非常小心地在所有运行 apiserver 的、可能需要对此 webhook +除非你非常小心地在所有运行 apiserver 的、可能需要对此 Webhook 进行调用的主机上运行。这样的安装方式可能不具有可移植性，即很难在新集群中启用。 使用用户或基本身份验证（例如："user:password@"）是不允许的。 使用片段（"#..."）和查询参数（"?..."）也是不允许的。 @@ -1321,14 +1350,16 @@ webhooks: path: /my-path port: 1234 ``` + {{< note >}} 你必须在以上示例中将 `` 替换为一个有效的 VA 证书包， 这是一个用 PEM 编码的 CA 证书包，用于校验 Webhook 的服务器证书。 {{< /note >}} + @@ -1342,7 +1373,7 @@ Webhook 通常仅对发送给他们的 `AdmissionReview` 内容进行操作。 但是，某些 Webhook 在处理 admission 请求时会进行带外更改。 -Webhook 使用 webhook 配置中的 `sideEffects` 字段显示它们是否有副作用： +Webhook 使用 Webhook 配置中的 `sideEffects` 字段显示它们是否有副作用： -* `None`：调用 webhook 没有副作用。 -* `NoneOnDryRun`：调用 webhook 可能会有副作用，但是如果将带有 `dryRun: true` - 属性的请求发送到 webhook，则 webhook 将抑制副作用（该 webhook 可识别 `dryRun`）。 +* `None`：调用 Webhook 没有副作用。 +* `NoneOnDryRun`：调用 Webhook 可能会有副作用，但是如果将带有 `dryRun: true` + 属性的请求发送到 webhook，则 Webhook 将抑制副作用（该 Webhook 可识别 `dryRun`）。 -这是一个 validating webhook 的示例，表明它对 `dryRun: true` 请求没有副作用： +这是一个 validating Webhook 的示例，表明它对 `dryRun: true` 请求没有副作用： ```yaml apiVersion: admissionregistration.k8s.io/v1 @@ -1427,8 +1458,8 @@ webhooks: timeoutSeconds: 2 ``` - 准入 Webhook 所用的超时时间默认为 10 秒。 @@ -1464,9 +1495,9 @@ and mutating webhooks can specify a `reinvocationPolicy` to control whether they 可以将 `reinvocationPolicy` 设置为 `Never` 或 `IfNeeded`。 默认为 `Never`。 * `Never`: 在一次准入测试中，不得多次调用 Webhook。 * `IfNeeded`: 如果在最初的 Webhook 调用之后被其他对象的插件修改了被接纳的对象， @@ -1479,9 +1510,11 @@ The important elements to note are: * 不能保证附加调用的次数恰好是一。 * 如果其他调用导致对该对象的进一步修改，则不能保证再次调用 Webhook。 @@ -1490,7 +1523,8 @@ The important elements to note are: （推荐用于有副作用的 Webhook）。 这是一个修改性质的 Webhook 的示例，该 Webhook 在以后的准入插件修改对象时被重新调用： @@ -1510,7 +1544,7 @@ in an object could already exist in the user-provided object, but it is essentia 修改性质的 Webhook 必须具有[幂等](#idempotence)性，并且能够成功处理 已被接纳并可能被修改的对象的修改性质的 Webhook。 对于所有修改性质的准入 Webhook 都是如此，因为它们可以在对象中进行的 -任何更改可能已经存在于用户提供的对象中，但是对于选择重新调用的 webhook +任何更改可能已经存在于用户提供的对象中，但是对于选择重新调用的 Webhook 来说是必不可少的。 -`failurePolicy` 定义了如何处理准入 webhook 中无法识别的错误和超时错误。允许的值为 `Ignore` 或 `Fail`。 +`failurePolicy` 定义了如何处理准入 Webhook 中无法识别的错误和超时错误。允许的值为 `Ignore` 或 `Fail`。 -* `Ignore` 表示调用 webhook 的错误将被忽略并且允许 API 请求继续。 -* `Fail` 表示调用 webhook 的错误导致准入失败并且 API 请求被拒绝。 +* `Ignore` 表示调用 Webhook 的错误将被忽略并且允许 API 请求继续。 +* `Fail` 表示调用 Webhook 的错误导致准入失败并且 API 请求被拒绝。 这是一个修改性质的 webhook，配置为在调用准入 Webhook 遇到错误时拒绝 API 请求： @@ -1542,8 +1576,8 @@ webhooks: failurePolicy: Fail ``` - 准入 Webhook 所用的默认 `failurePolicy` 是 `Fail`。 @@ -1560,14 +1594,13 @@ monitoring mechanisms help cluster admins to answer questions like: 2. What change did the mutating webhook applied to the object? -3. Which webhooks are frequently rejecting API requests? What's the reason for a - rejection? +3. Which webhooks are frequently rejecting API requests? What's the reason for a rejection? --> API 服务器提供了监视准入 Webhook 行为的方法。这些监视机制可帮助集群管理员回答以下问题： -1. 哪个修改性质的 webhook 改变了 API 请求中的对象？ +1. 哪个修改性质的 Webhook 改变了 API 请求中的对象？ 2. 修改性质的 Webhook 对对象做了哪些更改？ -3. 哪些 webhook 经常拒绝 API 请求？是什么原因拒绝？ +3. 哪些 Webhook 经常拒绝 API 请求？是什么原因拒绝？ - 在 `Metadata` 或更高审计级别上，将使用 JSON 负载记录带有键名 -`mutation.webhook.admission.k8s.io/round_{round idx}_index_{order idx}` 的注解， -该注解表示针对给定请求调用了 Webhook，以及该 Webhook 是否更改了对象。 + `mutation.webhook.admission.k8s.io/round_{round idx}_index_{order idx}` 的注解， + 该注解表示针对给定请求调用了 Webhook，以及该 Webhook 是否更改了对象。 有时，了解哪些准入 Webhook 经常拒绝 API 请求以及拒绝的原因是很有用的。 @@ -1757,20 +1791,22 @@ metrics are labelled to identify the causes of webhook rejection(s): - `type`: the admission webhook type, can be one of `admit` and `validating`. - `error_type`: identifies if an error occurred during the webhook invocation that caused the rejection. Its value can be one of: - - `calling_webhook_error`: unrecognized errors or timeout errors from the admission webhook happened and the - webhook's [Failure policy](#failure-policy) is set to `Fail`. - - `no_error`: no error occurred. The webhook rejected the request with `allowed: false` in the admission - response. The metrics label `rejection_code` records the `.status.code` set in the admission response. - - `apiserver_internal_error`: an API server internal error happened. + + - `calling_webhook_error`: unrecognized errors or timeout errors from the admission webhook happened and the + webhook's [Failure policy](#failure-policy) is set to `Fail`. + - `no_error`: no error occurred. The webhook rejected the request with `allowed: false` in the admission + response. The metrics label `rejection_code` records the `.status.code` set in the admission response. + - `apiserver_internal_error`: an API server internal error happened. + - `rejection_code`: the HTTP status code set in the admission response when a webhook rejected a request. --> - `name`：拒绝请求 Webhook 的名称。 - `operation`：请求的操作类型可以是 `CREATE`、`UPDATE`、`DELETE` 和 `CONNECT` 其中之一。 -- `type`：Admission webhook 类型，可以是 `admit` 和 `validating` 其中之一。 -- `error_type`：标识在 webhook 调用期间是否发生了错误并且导致了拒绝。其值可以是以下之一： +- `type`：Admission Webhook 类型，可以是 `admit` 和 `validating` 其中之一。 +- `error_type`：标识在 Webhook 调用期间是否发生了错误并且导致了拒绝。其值可以是以下之一： - `calling_webhook_error`：发生了来自准入 Webhook 的无法识别的错误或超时错误， - 并且 webhook 的 [失败策略](#failure-policy) 设置为 `Fail`。 + 并且 Webhook 的 [失败策略](#failure-policy) 设置为 `Fail`。 - `no_error`：未发生错误。Webhook 在准入响应中以 `allowed: false` 值拒绝了请求。 度量标签 `rejection_code` 记录了在准入响应中设置的 `.status.code`。 - `apiserver_internal_error`：apiserver 发生内部错误。 @@ -1815,7 +1851,8 @@ the initial application. 2. For a `CREATE` pod request, if the field `.spec.containers[].resources.limits` of a container is not set, set default resource limits. -3. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar` if no container with the name `foo-sidecar` already exists. +3. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar` if no container + with the name `foo-sidecar` already exists. In the cases above, the webhook can be safely reinvoked, or admit an object that already has the fields set. --> @@ -1891,16 +1928,18 @@ versions. See [Matching requests: matchPolicy](#matching-requests-matchpolicy) f ### 可用性 {#availability} -建议准入 webhook 尽快完成执行（时长通常是毫秒级），因为它们会增加 API 请求的延迟。 +建议准入 Webhook 尽快完成执行（时长通常是毫秒级），因为它们会增加 API 请求的延迟。 建议对 Webhook 使用较小的超时值。有关更多详细信息，请参见[超时](#timeouts)。 建议 Admission Webhook 应该采用某种形式的负载均衡机制，以提供高可用性和高性能。 @@ -1912,9 +1951,11 @@ to leverage the load-balancing that service supports. Admission webhooks that need to guarantee they see the final state of the object in order to enforce policy should use a validating admission webhook, since objects can be modified after being seen by mutating webhooks. -For example, a mutating admission webhook is configured to inject a sidecar container with name "foo-sidecar" on every -`CREATE` pod request. If the sidecar *must* be present, a validating admisson webhook should also be configured to intercept `CREATE` pod requests, and validate -that a container with name "foo-sidecar" with the expected configuration exists in the to-be-created object. +For example, a mutating admission webhook is configured to inject a sidecar container with name +"foo-sidecar" on every `CREATE` pod request. If the sidecar *must* be present, a validating +admisson webhook should also be configured to intercept `CREATE` pod requests, and validate that a +container with name "foo-sidecar" with the expected configuration exists in the to-be-created +object. --> ### 确保看到对象的最终状态 {#guaranteeing-the-final-state-of-the-object-is-seen} @@ -1923,7 +1964,7 @@ that a container with name "foo-sidecar" with the expected configuration exists 则应该使用一个验证性质的 webhook， 因为可以通过 mutating Webhook 看到对象后对其进行修改。 -例如，一个修改性质的准入Webhook 被配置为在每个 `CREATE` Pod 请求中 +例如，一个修改性质的准入 Webhook 被配置为在每个 `CREATE` Pod 请求中 注入一个名称为 "foo-sidecar" 的 sidecar 容器。 如果*必须*存在边车容器，则还应配置一个验证性质的准入 Webhook 以拦截 @@ -1942,7 +1983,8 @@ When a node that runs the webhook server pods becomes unhealthy, the webhook deployment will try to reschedule the pods to another node. However the requests will get rejected by the existing webhook server since the `"env"` label is unset, and the migration cannot happen. -It is recommended to exclude the namespace where your webhook is running with a [namespaceSelector](#matching-requests-namespaceselector). +It is recommended to exclude the namespace where your webhook is running with a +[namespaceSelector](#matching-requests-namespaceselector). --> ### 避免自托管的 Webhooks 中出现死锁 {#avoiding-deadlocks-in-self-hosted-webhooks} @@ -1971,7 +2013,7 @@ set to `NoneOnDryRun`. See [Side effects](#side-effects) for more detail. --> ### 副作用 {#side-effects} -建议准入 Webhook 应尽可能避免副作用，这意味着该准入 webhook 仅对发送给他们的 +建议准入 Webhook 应尽可能避免副作用，这意味着该准入 Webhook 仅对发送给他们的 `AdmissionReview` 的内容起作用，并且不要进行额外更改。 如果 Webhook 没有任何副作用，则 `.webhooks[].sideEffects` 字段应设置为 `None`。