你正在查看的文档所针对的是 Kubernetes 版本： v1.31

Kubernetes v1.31 版本的文档已不再维护。你现在看到的版本来自于一份静态的快照。如需查阅最新文档，请点击最新版本。

动态准入控制

除了内置的 admission 插件，准入插件可以作为扩展独立开发，并以运行时所配置的 Webhook 的形式运行。此页面描述了如何构建、配置、使用和监视准入 Webhook。

什么是准入 Webhook？

准入 Webhook 是一种用于接收准入请求并对其进行处理的 HTTP 回调机制。可以定义两种类型的准入 Webhook，即验证性质的准入 Webhook 和变更性质的准入 Webhook。变更性质的准入 Webhook 会先被调用。它们可以修改发送到 API 服务器的对象以执行自定义的设置默认值操作。

在完成了所有对象修改并且 API 服务器也验证了所传入的对象之后，验证性质的 Webhook 会被调用，并通过拒绝请求的方式来强制实施自定义的策略。

说明：

如果准入 Webhook 需要保证它们所看到的是对象的最终状态以实施某种策略。则应使用验证性质的准入 Webhook，因为对象被修改性质 Webhook 看到之后仍然可能被修改。

尝试准入 Webhook

准入 Webhook 本质上是集群控制平面的一部分。你应该非常谨慎地编写和部署它们。如果你打算编写或者部署生产级准入 Webhook，请阅读用户指南以获取相关说明。在下文中，我们将介绍如何快速试验准入 Webhook。

先决条件

确保启用 MutatingAdmissionWebhook 和 ValidatingAdmissionWebhook 控制器。这里是一组推荐的准入控制器，通常可以启用。
确保启用了 admissionregistration.k8s.io/v1 API。

编写一个准入 Webhook 服务器

请参阅 Kubernetes e2e 测试中的 Admission Webhook 服务器的实现。 Webhook 处理由 API 服务器发送的 AdmissionReview 请求，并且将其决定作为 AdmissionReview 对象以相同版本发送回去。

有关发送到 Webhook 的数据的详细信息，请参阅 Webhook 请求。

要获取来自 Webhook 的预期数据，请参阅 Webhook 响应。

示例准入 Webhook 服务器置 ClientAuth 字段为空，默认为 NoClientCert 。这意味着 Webhook 服务器不会验证客户端的身份，认为其是 API 服务器。如果你需要双向 TLS 或其他方式来验证客户端，请参阅如何对 API 服务器进行身份认证。

部署准入 Webhook 服务

e2e 测试中的 Webhook 服务器通过 deployment API 部署在 Kubernetes 集群中。该测试还将创建一个 Service 作为 Webhook 服务器的前端。参见相关代码。

你也可以在集群外部署 Webhook。这样做需要相应地更新你的 Webhook 配置。

即时配置准入 Webhook

你可以通过 ValidatingWebhookConfiguration 或者 MutatingWebhookConfiguration 动态配置哪些资源要被哪些准入 Webhook 处理。

以下是一个 ValidatingWebhookConfiguration 示例，Mutating Webhook 配置与此类似。有关每个配置字段的详细信息，请参阅 Webhook 配置部分。

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "pod-policy.example.com"
webhooks:
- name: "pod-policy.example.com"
  rules:
  - apiGroups: [""]
    apiVersions: ["v1"]
    operations: ["CREATE"]
    resources: ["pods"]
    scope: "Namespaced"
  clientConfig:
    service:
      namespace: "example-namespace"
      name: "example-service"
    caBundle: <CA_BUNDLE>
  admissionReviewVersions: ["v1"]
  sideEffects: None
  timeoutSeconds: 5

说明：

你必须在以上示例中将 <CA_BUNDLE> 替换为一个有效的 CA 证书包，这是一个用 PEM 编码的（字段值是 Base64 编码）CA 证书包，用于校验 Webhook 的服务器证书。

scope 字段指定是仅集群范围的资源（Cluster）还是名字空间范围的资源资源（Namespaced）将与此规则匹配。 * 表示没有范围限制。

说明：

当使用 clientConfig.service 时，服务器证书必须对 <svc_name>.<svc_namespace>.svc 有效。

说明：

Webhook 调用的默认超时是 10 秒，你可以设置 timeout 并建议对 Webhook 设置较短的超时时间。如果 Webhook 调用超时，则根据 Webhook 的失败策略处理请求。

当一个 API 服务器收到与 rules 相匹配的请求时，该 API 服务器将按照 clientConfig 中指定的方式向 Webhook 发送一个 admissionReview 请求。

创建 Webhook 配置后，系统将花费几秒钟使新配置生效。

对 API 服务器进行身份认证

如果你的 Webhook 需要身份验证，则可以将 API 服务器配置为使用基本身份验证、持有者令牌或证书来向 Webhook 提供身份证明。完成此配置需要三个步骤。

启动 API 服务器时，通过 --admission-control-config-file 参数指定准入控制配置文件的位置。
在准入控制配置文件中，指定 MutatingAdmissionWebhook 控制器和 ValidatingAdmissionWebhook 控制器应该读取凭据的位置。凭证存储在 kubeConfig 文件中（是的，与 kubectl 使用的模式相同），因此字段名称为 kubeConfigFile。以下是一个准入控制配置文件示例：

apiserver.config.k8s.io/v1
apiserver.k8s.io/v1alpha1

apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: ValidatingAdmissionWebhook
  configuration:
    apiVersion: apiserver.config.k8s.io/v1
    kind: WebhookAdmissionConfiguration
    kubeConfigFile: "<path-to-kubeconfig-file>"
- name: MutatingAdmissionWebhook
  configuration:
    apiVersion: apiserver.config.k8s.io/v1
    kind: WebhookAdmissionConfiguration
    kubeConfigFile: "<path-to-kubeconfig-file>"

# 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
    apiVersion: apiserver.config.k8s.io/v1alpha1
    kind: WebhookAdmission
    kubeConfigFile: "<path-to-kubeconfig-file>"
- name: MutatingAdmissionWebhook
  configuration:
    # 1.17 中被弃用，推荐使用 apiserver.config.k8s.io/v1，kind = WebhookAdmissionConfiguration
    apiVersion: apiserver.config.k8s.io/v1alpha1
    kind: WebhookAdmission
    kubeConfigFile: "<path-to-kubeconfig-file>"

有关 AdmissionConfiguration 的更多信息，请参见 AdmissionConfiguration (v1) reference。有关每个配置字段的详细信息，请参见 Webhook 配置部分。

在 kubeConfig 文件中，提供证书凭据：

apiVersion: v1
kind: Config
users:
# name 应设置为服务的 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: "<pem encoded certificate>"
    client-key-data: "<pem encoded key>"
# `name` 支持使用 * 通配符匹配前缀段。
- name: '*.webhook-company.org'
  user:
    password: "<password>"
    username: "<name>"
# '*' 是默认匹配项。
- name: '*'
  user:
    token: "<token>"

当然，你需要设置 Webhook 服务器来处理这些身份验证请求。

Webhook 请求与响应

请求

Webhook 发送 POST 请求时，请设置 Content-Type: application/json 并对 admission.k8s.io API 组中的 AdmissionReview 对象进行序列化，将所得到的 JSON 作为请求的主体。

Webhook 可以在配置中的 admissionReviewVersions 字段指定可接受的 AdmissionReview 对象版本：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
- name: my-webhook.example.com
  admissionReviewVersions: ["v1", "v1beta1"]

创建 Webhook 配置时，admissionReviewVersions 是必填字段。 Webhook 必须支持至少一个当前和以前的 API 服务器都可以解析的 AdmissionReview 版本。

API 服务器将发送的是 admissionReviewVersions 列表中所支持的第一个 AdmissionReview 版本。如果 API 服务器不支持列表中的任何版本，则不允许创建配置。

如果 API 服务器遇到以前创建的 Webhook 配置，并且不支持该 API 服务器知道如何发送的任何 AdmissionReview 版本，则调用 Webhook 的尝试将失败，并依据失败策略进行处理。

此示例显示了 AdmissionReview 对象中包含的数据，该数据用于请求更新 apps/v1 Deployment 的 scale 子资源：

apiVersion: admission.k8s.io/v1
kind: AdmissionReview
request:
  # 唯一标识此准入回调的随机 uid
  uid: 705ab4f5-6393-11e8-b7cc-42010a800002

  # 传入完全限定的 group/version/kind 对象
  kind:
    group: autoscaling
    version: v1
    kind: Scale

  # 修改 resource 的完全限定 group/version/kind
  resource:
    group: apps
    version: v1
    resource: deployments

  # subResource（如果请求是针对 subResource 的）
  subResource: scale

  # 在对 API 服务器的原始请求中，传入对象的标准 group/version/kind
  # 仅当 Webhook 指定 `matchPolicy: Equivalent` 且将对 API 服务器的原始请求
  # 转换为 Webhook 注册的版本时，这才与 `kind` 不同。
  requestKind:
    group: autoscaling
    version: v1
    kind: Scale

  # 在对 API 服务器的原始请求中正在修改的资源的标准 group/version/kind
  # 仅当 Webhook 指定了 `matchPolicy：Equivalent` 并且将对 API 服务器的原始请求转换为
  # Webhook 注册的版本时，这才与 `resource` 不同。
  requestResource:
    group: apps
    version: v1
    resource: deployments

  # subResource（如果请求是针对 subResource 的）
  # 仅当 Webhook 指定了 `matchPolicy：Equivalent` 并且将对
  # API 服务器的原始请求转换为该 Webhook 注册的版本时，这才与 `subResource` 不同。
  requestSubResource: scale

  # 被修改资源的名称
  name: my-deployment

  # 如果资源是属于名字空间（或者是名字空间对象），则这是被修改的资源的名字空间
  namespace: my-namespace

  # 操作可以是 CREATE、UPDATE、DELETE 或 CONNECT
  operation: UPDATE

  userInfo:
    # 向 API 服务器发出请求的经过身份验证的用户的用户名
    username: admin

    # 向 API 服务器发出请求的经过身份验证的用户的 UID
    uid: 014fbff9a07c

    # 向 API 服务器发出请求的经过身份验证的用户的组成员身份
    groups:
      - system:authenticated
      - my-admin-group
    # 向 API 服务器发出请求的用户相关的任意附加信息
    # 该字段由 API 服务器身份验证层填充，并且如果 webhook 执行了任何
    # SubjectAccessReview 检查，则应将其包括在内。
    extra:
      some-key:
        - some-value1
        - some-value2

  # object 是被接纳的新对象。
  # 对于 DELETE 操作，它为 null。
  object:
    apiVersion: autoscaling/v1
    kind: Scale

  # oldObject 是现有对象。
  # 对于 CREATE 和 CONNECT 操作，它为 null。
  oldObject:
    apiVersion: autoscaling/v1
    kind: Scale

  # options 包含要接受的操作的选项，例如 meta.k8s.io/v CreateOptions、UpdateOptions 或 DeleteOptions。
  # 对于 CONNECT 操作，它为 null。
  options:
    apiVersion: meta.k8s.io/v1
    kind: UpdateOptions

  # dryRun 表示 API 请求正在以 `dryrun` 模式运行，并且将不会保留。
  # 带有副作用的 Webhook 应该避免在 dryRun 为 true 时激活这些副作用。
  # 有关更多详细信息，请参见 http://k8s.io/zh-cn/docs/reference/using-api/api-concepts/#make-a-dry-run-request
  dryRun: False

响应

Webhook 使用 HTTP 200 状态码、Content-Type: application/json 和一个包含 AdmissionReview 对象的 JSON 序列化格式来发送响应。该 AdmissionReview 对象与发送的版本相同，且其中包含的 response 字段已被有效填充。

response 至少必须包含以下字段：

uid，从发送到 Webhook 的 request.uid 中复制而来
allowed，设置为 true 或 false

Webhook 允许请求的最简单响应示例：

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true
  }
}

Webhook 禁止请求的最简单响应示例：

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": false
  }
}

当拒绝请求时，Webhook 可以使用 status 字段自定义 http 响应码和返回给用户的消息。有关状态类型的详细信息，请参见 API 文档。禁止请求的响应示例，它定制了向用户显示的 HTTP 状态码和消息：

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": false,
    "status": {
      "code": 403,
      "message": "You cannot do this because it is Tuesday and your name starts with A"
    }
  }
}

当允许请求时，mutating准入 Webhook 也可以选择修改传入的对象。这是通过在响应中使用 patch 和 patchType 字段来完成的。当前唯一支持的 patchType 是 JSONPatch。有关更多详细信息，请参见 JSON patch。对于 patchType: JSONPatch，patch 字段包含一个以 base64 编码的 JSON patch 操作数组。

例如，设置 spec.replicas 的单个补丁操作将是 [{"op": "add", "path": "/spec/replicas", "value": 3}]。

如果以 Base64 形式编码，结果将是 W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0=

因此，添加该标签的 Webhook 响应为：

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true,
    "patchType": "JSONPatch",
    "patch": "W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0="
  }
}

准入 Webhook 可以选择性地返回在 HTTP Warning 头中返回给请求客户端的警告消息，警告代码为 299。警告可以与允许或拒绝的准入响应一起发送。

如果你正在实现返回一条警告的 Webhook，则：

不要在消息中包括 "Warning:" 前缀
使用警告消息描述该客户端进行 API 请求时会遇到或应意识到的问题
如果可能，将警告限制为 120 个字符

注意：

超过 256 个字符的单条警告消息在返回给客户之前可能会被 API 服务器截断。如果超过 4096 个字符的警告消息（来自所有来源），则额外的警告消息会被忽略。

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "<value from request.uid>",
    "allowed": true,
    "warnings": [
      "duplicate envvar entries specified with name MY_ENV",
      "memory request less than 4MB specified for container mycontainer, which will not start successfully"
    ]
  }
}

Webhook 配置

要注册准入 Webhook，请创建 MutatingWebhookConfiguration 或 ValidatingWebhookConfiguration API 对象。 MutatingWebhookConfiguration 或ValidatingWebhookConfiguration 对象的名称必须是有效的 DNS 子域名。

每种配置可以包含一个或多个 Webhook。如果在单个配置中指定了多个 Webhook，则应为每个 Webhook 赋予一个唯一的名称。这是必需的，以使生成的审计日志和指标更易于与激活的配置相匹配。

每个 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 子资源。
scope 指定要匹配的范围。有效值为 "Cluster"、"Namespaced" 和 "*"。子资源匹配其父资源的范围。默认值为 "*"。
- "Cluster" 表示只有集群作用域的资源才能匹配此规则（API 对象 Namespace 是集群作用域的）。
- "Namespaced" 意味着仅具有名字空间的资源才符合此规则。
- "*" 表示没有作用域限制。

如果传入请求与任何 Webhook rules 的指定 operations、groups、versions、 resources 和 scope 匹配，则该请求将发送到 Webhook。

以下是可用于指定应拦截哪些资源的规则的其他示例。

匹配针对 apps/v1 和 apps/v1beta1 组中 deployments 和 replicasets 资源的 CREATE 或 UPDATE 请求：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
...
webhooks:
- name: my-webhook.example.com
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["apps"]
    apiVersions: ["v1", "v1beta1"]
    resources: ["deployments", "replicasets"]
    scope: "Namespaced"
  ...

匹配所有 API 组和版本中的所有资源（但不包括子资源）的创建请求：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    rules:
      - operations: ["CREATE"]
        apiGroups: ["*"]
        apiVersions: ["*"]
        resources: ["*"]
        scope: "*"

匹配所有 API 组和版本中所有 status 子资源的更新请求：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    rules:
      - operations: ["UPDATE"]
        apiGroups: ["*"]
        apiVersions: ["*"]
        resources: ["*/status"]
        scope: "*"

匹配请求：objectSelector

通过指定 objectSelector，Webhook 能够根据可能发送的对象的标签来限制哪些请求被拦截。如果指定，则将对 objectSelector 和可能发送到 Webhook 的 object 和 oldObject 进行评估。如果两个对象之一与选择算符匹配，则认为该请求已匹配。

空对象（对于创建操作而言为 oldObject，对于删除操作而言为 newObject），或不能带标签的对象（例如 DeploymentRollback 或 PodProxyOptions 对象）被认为不匹配。

仅当选择使用 Webhook 时才使用对象选择器，因为最终用户可以通过设置标签来跳过准入 Webhook。

这个例子展示了一个变更性质的 Webhook，它将匹配带有标签 foo:bar 的所有资源（但不包括子资源）的 CREATE 操作：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
webhooks:
- name: my-webhook.example.com
  objectSelector:
    matchLabels:
      foo: bar
  rules:
  - operations: ["CREATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["*"]
    scope: "*"

有关标签选择算符的更多示例，请参见标签的概念。

匹配请求：namespaceSelector

通过指定 namespaceSelector， Webhook 可以根据具有名字空间的资源所处的名字空间的标签来选择拦截哪些资源的操作。

namespaceSelector 根据名字空间的标签是否匹配选择算符，决定是否针对具名字空间的资源（或 Namespace 对象）的请求运行 Webhook。如果对象是除 Namespace 以外的集群范围的资源，则 namespaceSelector 标签无效。

本例给出的变更性质的 Webhook 将匹配到对名字空间中具名字空间的资源的 CREATE 请求，前提是这些资源不含值为 "0" 或 "1" 的 "runlevel" 标签：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    namespaceSelector:
      matchExpressions:
        - key: runlevel
          operator: NotIn
          values: ["0", "1"]
    rules:
      - operations: ["CREATE"]
        apiGroups: ["*"]
        apiVersions: ["*"]
        resources: ["*"]
        scope: "Namespaced"

此示例显示了一个验证性质的 Webhook，它将匹配到对某名字空间中的任何具名字空间的资源的 CREATE 请求，前提是该名字空间具有值为 "prod" 或 "staging" 的 "environment" 标签：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    namespaceSelector:
      matchExpressions:
        - key: environment
          operator: In
          values: ["prod", "staging"]
    rules:
      - operations: ["CREATE"]
        apiGroups: ["*"]
        apiVersions: ["*"]
        resources: ["*"]
        scope: "Namespaced"

有关标签选择算符的更多示例，请参见标签的概念。

匹配请求：matchPolicy

API 服务器可以通过多个 API 组或版本来提供对象。

例如，如果一个 Webhook 仅为某些 API 组/版本指定了规则（例如 apiGroups:["apps"], apiVersions:["v1","v1beta1"]），而修改资源的请求是通过另一个 API 组/版本（例如 extensions/v1beta1）发出的，该请求将不会被发送到 Webhook。

matchPolicy 允许 Webhook 定义如何使用其 rules 匹配传入的请求。允许的值为 Exact 或 Equivalent。

Exact 表示仅当请求与指定规则完全匹配时才应拦截该请求。
Equivalent 表示如果某个请求意在修改 rules 中列出的资源，即使该请求是通过其他 API 组或版本发起，也应拦截该请求。

在上面给出的示例中，仅为 apps/v1 注册的 Webhook 可以使用 matchPolicy：

matchPolicy: Exact 表示不会将 extensions/v1beta1 请求发送到 Webhook
matchPolicy:Equivalent 表示将 extensions/v1beta1 请求发送到 Webhook （将对象转换为 Webhook 指定的版本：apps/v1）

建议指定 Equivalent，确保升级后启用 API 服务器中资源的新版本时， Webhook 继续拦截他们期望的资源。

当 API 服务器停止提供某资源时，该资源不再被视为等同于该资源的其他仍在提供服务的版本。例如，extensions/v1beta1 中的 Deployment 已被废弃，计划在 v1.16 中移除。

移除后，带有 apiGroups:["extensions"], apiVersions:["v1beta1"], resources: ["deployments"] 规则的 Webhook 将不再拦截通过 apps/v1 API 来创建的 Deployment。因此，Webhook 应该优先注册稳定版本的资源。

此示例显示了一个验证性质的 Webhook，该 Webhook 拦截对 Deployment 的修改（无论 API 组或版本是什么），始终会发送一个 apps/v1 版本的 Deployment 对象：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
- name: my-webhook.example.com
  matchPolicy: Equivalent
  rules:
  - operations: ["CREATE","UPDATE","DELETE"]
    apiGroups: ["apps"]
    apiVersions: ["v1"]
    resources: ["deployments"]
    scope: "Namespaced"

准入 Webhook 所用的 matchPolicy 默认为 Equivalent。

匹配请求：`matchConditions`

特性状态： Kubernetes v1.30 [stable] (enabled by default: true)

如果你需要细粒度地过滤请求，你可以为 Webhook 定义匹配条件。如果你发现匹配规则、objectSelectors 和 namespaceSelectors 仍然不能提供你想要的何时进行 HTTP 调用的过滤条件，那么添加这些条件会很有用。匹配条件是 CEL 表达式。所有匹配条件都必须为 true 才能调用 Webhook。

以下是一个例子，说明了匹配条件的几种不同用法：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    matchPolicy: Equivalent
    rules:
      - operations: ['CREATE','UPDATE']
        apiGroups: ['*']
        apiVersions: ['*']
        resources: ['*']
    failurePolicy: 'Ignore' # 失败时继续处理请求但跳过 Webhook (可选值)
    sideEffects: None
    clientConfig:
      service:
        namespace: my-namespace
        name: my-webhook
      caBundle: '<omitted>'
    # 你可以为每个 Webhook 配置最多 64 个 matchConditions
    matchConditions:
      - name: 'exclude-leases' # 每个匹配条件必须有唯一的名称
        expression: '!(request.resource.group == "coordination.k8s.io" && request.resource.resource == "leases")' # 匹配非租约资源
      - name: 'exclude-kubelet-requests'
        expression: '!("system:nodes" in request.userInfo.groups)' # 匹配非节点用户发出的请求
      - name: 'rbac' # 跳过 RBAC 请求，该请求将由第二个 Webhook 处理
        expression: 'request.resource.group != "rbac.authorization.k8s.io"'

  # 这个示例演示了如何使用 “authorizer”。
  # 授权检查比简单的表达式更复杂，因此在这个示例中，使用第二个 Webhook 来针对 RBAC 请求进行处理。
  # 两个 Webhook 都可以由同一个端点提供服务。
  - name: rbac.my-webhook.example.com
    matchPolicy: Equivalent
    rules:
      - operations: ['CREATE','UPDATE']
        apiGroups: ['rbac.authorization.k8s.io']
        apiVersions: ['*']
        resources: ['*']
    failurePolicy: 'Fail' # 失败时拒绝请求 (默认值)
    sideEffects: None
    clientConfig:
      service:
        namespace: my-namespace
        name: my-webhook
      caBundle: '<omitted>'
    # 你可以为每个 Webhook 配置最多 64 个 matchConditions
    matchConditions:
      - name: 'breakglass'
        # 跳过由授权给 “breakglass” 的用户在这个 Webhook 上发起的请求。
        # “breakglass” API 不需要在这个检查之外存在。
        expression: '!authorizer.group("admissionregistration.k8s.io").resource("validatingwebhookconfigurations").name("my-webhook.example.com").check("breakglass").allowed()'

说明：

你可以为每个 Webhook 在 matchConditions 字段中定义最多 64 个匹配条件。

匹配条件可以访问以下 CEL 变量：

object - 来自传入请求的对象。对于 DELETE 请求，该值为 null。该对象版本可能根据 matchPolicy 进行转换。
oldObject - 现有对象。对于 CREATE 请求，该值为 null。
request - AdmissionReview 的请求部分，不包括 object 和 oldObject。
authorizer - 一个 CEL 鉴权组件。可用于对请求的主体（经过身份认证的用户）执行鉴权检查。更多详细信息，请参阅 Kubernetes CEL 库文档中的 Authz。
authorizer.requestResource - 对配置的请求资源（组、资源、（子资源）、名字空间、名称）进行授权检查的快捷方式。

了解有关 CEL 表达式的更多信息，请参阅 Kubernetes 参考文档中的通用表达式语言。

如果在对匹配条件求值时出现错误，则不会调用 Webhook。根据以下方式确定是否拒绝请求：

如果任何一个匹配条件求值结果为 false（不管其他错误），API 服务器将跳过 Webhook。
否则：
- 对于 failurePolicy: Fail，拒绝请求（不调用 Webhook）。
- 对于 failurePolicy: Ignore，继续处理请求但跳过 Webhook。

调用 Webhook

API 服务器确定请求应发送到 Webhook 后，它需要知道如何调用 Webhook。此信息在 Webhook 配置的 clientConfig 节中指定。

Webhook 可以通过 URL 或服务引用来调用，并且可以选择包含自定义 CA 包，以用于验证 TLS 连接。

URL

url 以标准 URL 形式给出 Webhook 的位置（scheme://host:port/path）。

host 不应引用集群中运行的服务；通过指定 service 字段来使用服务引用。主机可以通过某些 API 服务器中的外部 DNS 进行解析。（例如，kube-apiserver 无法解析集群内 DNS，因为这将违反分层规则）。host 也可以是 IP 地址。

请注意，将 localhost 或 127.0.0.1 用作 host 是有风险的，除非你非常小心地在所有运行 apiserver 的、可能需要对此 Webhook 进行调用的主机上运行。这样的安装方式可能不具有可移植性，即很难在新集群中启用。

scheme 必须为 "https"；URL 必须以 "https://" 开头。

使用用户或基本身份验证（例如：user:password@）是不允许的。使用片段（#...）和查询参数（?...）也是不允许的。

这是配置为调用 URL 的变更性质的 Webhook 的示例（并且期望使用系统信任根证书来验证 TLS 证书，因此不指定 caBundle）：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
webhooks:
- name: my-webhook.example.com
  clientConfig:
    url: "https://my-webhook.example.com:9443/my-webhook-path"

服务引用

clientConfig 内部的 Service 是对该 Webhook 服务的引用。如果 Webhook 在集群中运行，则应使用 service 而不是 url。服务的 namespace 和 name 是必需的。 port 是可选的，默认值为 443。path 是可选的，默认为 "/"。

这是一个 mutating Webhook 的示例，该 mutating Webhook 配置为在子路径 "/my-path" 端口 "1234" 上调用服务，并使用自定义 CA 包针对 ServerName my-service-name.my-service-namespace.svc 验证 TLS 连接：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
webhooks:
- name: my-webhook.example.com
  clientConfig:
    caBundle: <CA_BUNDLE>
    service:
      namespace: my-service-namespace
      name: my-service-name
      path: /my-path
      port: 1234

说明：

你必须在以上示例中将 <CA_BUNDLE> 替换为一个有效的 VA 证书包，这是一个用 PEM 编码的 CA 证书包，用于校验 Webhook 的服务器证书。

副作用

Webhook 通常仅对发送给他们的 AdmissionReview 内容进行操作。但是，某些 Webhook 在处理 admission 请求时会进行带外更改。

进行带外更改的（产生“副作用”的）Webhook 必须具有协调机制（如控制器），该机制定期确定事物的实际状态，并调整由准入 Webhook 修改的带外数据以反映现实情况。这是因为对准入 Webhook 的调用不能保证所准入的对象将原样保留，或根本不保留。以后，Webhook 可以修改对象的内容，在写入存储时可能会发生冲突，或者服务器可以在持久保存对象之前关闭电源。

此外，处理 dryRun: true admission 请求时，具有副作用的 Webhook 必须避免产生副作用。一个 Webhook 必须明确指出在使用 dryRun 运行时不会有副作用，否则 dry-run 请求将不会发送到该 Webhook，而 API 请求将会失败。

Webhook 使用 Webhook 配置中的 sideEffects 字段显示它们是否有副作用：

None：调用 Webhook 没有副作用。
NoneOnDryRun：调用 Webhook 可能会有副作用，但是如果将带有 dryRun: true 属性的请求发送到 Webhook，则 Webhook 将抑制副作用（该 Webhook 可识别 dryRun）。

这是一个验证性质的 Webhook 的示例，表明它对 dryRun: true 请求没有副作用：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    sideEffects: NoneOnDryRun

超时

由于 Webhook 会增加 API 请求的延迟，因此应尽快完成自身的操作。 timeoutSeconds 用来配置在将调用视为失败之前，允许 API 服务器等待 Webhook 响应的时间长度。

如果超时在 Webhook 响应之前被触发，则基于失败策略，将忽略 Webhook 调用或拒绝 API 调用。

超时值必须设置在 1 到 30 秒之间。

这是一个自定义超时设置为 2 秒的 validating Webhook 的示例：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
webhooks:
  - name: my-webhook.example.com
    timeoutSeconds: 2

准入 Webhook 所用的超时时间默认为 10 秒。

再调用策略

变更性质的准入插件（包括 Webhook）的任何一种排序方式都不会适用于所有情况。 (参见 https://issue.k8s.io/64333 示例)。变更性质的 Webhook 可以向对象中添加新的子结构（例如向 pod 中添加 container），已经运行的其他修改插件可能会对这些新结构有影响（就像在所有容器上设置 imagePullPolicy 一样）。

要允许变更性质的准入插件感应到其他插件所做的更改，如果变更性质的 Webhook 修改了一个对象，则会重新运行内置的变更性质的准入插件，并且变更性质的 Webhook 可以指定 reinvocationPolicy 来控制是否也重新调用它们。

可以将 reinvocationPolicy 设置为 Never 或 IfNeeded。默认为 Never。

Never: 在一次准入测试中，不得多次调用 Webhook。
IfNeeded: 如果在最初的 Webhook 调用之后被其他对象的插件修改了被接纳的对象，则可以作为准入测试的一部分再次调用该 Webhook。

要注意的重要因素有：

不能保证附加调用的次数恰好是一。
如果其他调用导致对该对象的进一步修改，则不能保证再次调用 Webhook。
使用此选项的 Webhook 可能会重新排序，以最大程度地减少额外调用的次数。
要在确保所有修改都完成后验证对象，请改用验证性质的 Webhook （推荐用于有副作用的 Webhook）。

这是一个变更性质的 Webhook 的示例，该 Webhook 在以后的准入插件修改对象时被重新调用：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
webhooks:
- name: my-webhook.example.com
  reinvocationPolicy: IfNeeded

变更性质的 Webhook 必须具有幂等性，并且能够成功处理已被接纳并可能被修改的对象的变更性质的 Webhook。对于所有变更性质的准入 Webhook 都是如此，因为它们可以在对象中进行的任何更改可能已经存在于用户提供的对象中，但是对于选择重新调用的 Webhook 来说是必不可少的。

失败策略

failurePolicy 定义了如何处理准入 Webhook 中无法识别的错误和超时错误。允许的值为 Ignore 或 Fail。

Ignore 表示调用 Webhook 的错误将被忽略并且允许 API 请求继续。
Fail 表示调用 Webhook 的错误导致准入失败并且 API 请求被拒绝。

这是一个变更性质的 Webhook，配置为在调用准入 Webhook 遇到错误时拒绝 API 请求：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
webhooks:
- name: my-webhook.example.com
  failurePolicy: Fail

准入 Webhook 所用的默认 failurePolicy 是 Fail。

监控 Admission Webhook

API 服务器提供了监视准入 Webhook 行为的方法。这些监视机制可帮助集群管理员回答以下问题：

哪个变更性质的 Webhook 改变了 API 请求中的对象？
变更性质的 Webhook 对对象做了哪些更改？
哪些 Webhook 经常拒绝 API 请求？是什么原因拒绝？

变更性质的 Webhook 审计注解

有时，了解 API 请求中的哪个变更性质的 Webhook 使对象改变以及该 Webhook 应用了哪些更改很有用。

Kubernetes API 服务器针对每个变更性质的 Webhook 调用执行审计操作。每个调用都会生成一个审计注解，记述请求对象是否发生改变，可选地还可以根据 Webhook 的准入响应生成一个注解，记述所应用的修补。针对给定请求的给定执行阶段，注解被添加到审计事件中，然后根据特定策略进行预处理并写入后端。

事件的审计级别决定了要记录哪些注解：

在 Metadata 或更高审计级别上，将使用 JSON 负载记录带有键名 mutation.webhook.admission.k8s.io/round_{round idx}_index_{order idx} 的注解，该注解表示针对给定请求调用了 Webhook，以及该 Webhook 是否更改了对象。

例如，对于正在被重新调用的某 Webhook，所记录的注解如下。 Webhook 在 mutating Webhook 链中排在第三个位置，并且在调用期间未改变请求对象。

# 审计事件相关记录
{
    "kind": "Event",
    "apiVersion": "audit.k8s.io/v1",
    "annotations": {
        "mutation.webhook.admission.k8s.io/round_1_index_2": "{\"configuration\":\"my-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook.example.com\",\"mutated\": false}"
        # 其他注解
        ...
    }
    # 其他字段
    ...
}

# 反序列化的注解值
{
    "configuration": "my-mutating-webhook-configuration.example.com",
    "webhook": "my-webhook.example.com",
    "mutated": false
}

对于在第一轮中调用的 Webhook，所记录的注解如下。 Webhook 在变更性质的 Webhook 链中排在第一位，并在调用期间改变了请求对象。

# 审计事件相关记录
{
    "kind": "Event",
    "apiVersion": "audit.k8s.io/v1",
    "annotations": {
        "mutation.webhook.admission.k8s.io/round_0_index_0": "{\"configuration\":\"my-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook-always-mutate.example.com\",\"mutated\": true}"
        # 其他注解
        ...
    }
    # 其他字段
    ...
}

# 反序列化的注解值
{
    "configuration": "my-mutating-webhook-configuration.example.com",
    "webhook": "my-webhook-always-mutate.example.com",
    "mutated": true
}

在 Request 或更高审计级别上，将使用 JSON 负载记录带有键名为 patch.webhook.admission.k8s.io/round_{round idx}_index_{order idx} 的注解，该注解表明针对给定请求调用了 Webhook 以及应用于请求对象之上的修改。

例如，以下是针对正在被重新调用的某 Webhook 所记录的注解。 Webhook 在变更性质的 Webhook 链中排在第四，并在其响应中包含一个 JSON 补丁，该补丁已被应用于请求对象。

# 审计事件相关记录
{
    "kind": "Event",
    "apiVersion": "audit.k8s.io/v1",
    "annotations": {
        "patch.webhook.admission.k8s.io/round_1_index_3": "{\"configuration\":\"my-other-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook-always-mutate.example.com\",\"patch\":[{\"op\":\"add\",\"path\":\"/data/mutation-stage\",\"value\":\"yes\"}],\"patchType\":\"JSONPatch\"}"
        # 其他注解
        ...
    }
    # 其他字段
    ...
}

# 反序列化的注解值
{
    "configuration": "my-other-mutating-webhook-configuration.example.com",
    "webhook": "my-webhook-always-mutate.example.com",
    "patchType": "JSONPatch",
    "patch": [
        {
            "op": "add",
            "path": "/data/mutation-stage",
            "value": "yes"
        }
    ]
}

准入 Webhook 度量值

API 服务器从 /metrics 端点公开 Prometheus 指标，这些指标可用于监控和诊断 API 服务器状态。以下指标记录了与准入 Webhook 相关的状态。

apiserver 准入 Webhook 拒绝次数

有时，了解哪些准入 Webhook 经常拒绝 API 请求以及拒绝的原因是很有用的。

在 v1.16+ 中，kube-apiserver 提供了 Prometheus 计数器度量值，记录准入 Webhook 的拒绝次数。度量值的标签给出了 Webhook 拒绝该请求的原因：

name：拒绝请求 Webhook 的名称。
operation：请求的操作类型可以是 CREATE、UPDATE、DELETE 和 CONNECT 其中之一。
type：Admission Webhook 类型，可以是 admit 和 validating 其中之一。
error_type：标识在 Webhook 调用期间是否发生了错误并且导致了拒绝。其值可以是以下之一：
- calling_webhook_error：发生了来自准入 Webhook 的无法识别的错误或超时错误，并且 Webhook 的失败策略设置为 Fail。
- no_error：未发生错误。Webhook 在准入响应中以 allowed: false 值拒绝了请求。度量标签 rejection_code 记录了在准入响应中设置的 .status.code。
- apiserver_internal_error：apiserver 发生内部错误。
rejection_code：当 Webhook 拒绝请求时，在准入响应中设置的 HTTP 状态码。

拒绝计数指标示例：

# HELP apiserver_admission_webhook_rejection_count [ALPHA] Admission webhook rejection count, identified by name and broken out for each admission type (validating or admit) and operation. Additional labels specify an error type (calling_webhook_error or apiserver_internal_error if an error occurred; no_error otherwise) and optionally a non-zero rejection code if the webhook rejects the request with an HTTP status code (honored by the apiserver when the code is greater or equal to 400). Codes greater than 600 are truncated to 600, to keep the metrics cardinality bounded.
# TYPE apiserver_admission_webhook_rejection_count counter
apiserver_admission_webhook_rejection_count{error_type="calling_webhook_error",name="always-timeout-webhook.example.com",operation="CREATE",rejection_code="0",type="validating"} 1
apiserver_admission_webhook_rejection_count{error_type="calling_webhook_error",name="invalid-admission-response-webhook.example.com",operation="CREATE",rejection_code="0",type="validating"} 1
apiserver_admission_webhook_rejection_count{error_type="no_error",name="deny-unwanted-configmap-data.example.com",operation="CREATE",rejection_code="400",type="validating"} 13

最佳实践和警告

幂等性

幂等的变更性质的准入 Webhook 能够成功处理已经被它接纳甚或修改的对象。即使多次执行该准入测试，也不会产生与初次执行结果相异的结果。

幂等 mutating admission Webhook 的示例：

对于 CREATE Pod 请求，将 Pod 的字段 .spec.securityContext.runAsNonRoot 设置为 true，以实施安全最佳实践。
对于 CREATE Pod 请求，如果未设置容器的字段 .spec.containers[].resources.limits，设置默认资源限制值。
对于 CREATE Pod 请求，如果 Pod 中不存在名为 foo-sidecar 的边车容器，向 Pod 注入一个 foo-sidecar 容器。

在上述情况下，可以安全地重新调用 Webhook，或接受已经设置了字段的对象。

非幂等 mutating admission Webhook 的示例：

对于 CREATE Pod 请求，注入名称为 foo-sidecar 并带有当前时间戳的边车容器（例如 foo-sidecar-19700101-000000）。
对于 CREATE/UPDATE Pod 请求，如果容器已设置标签 "env" 则拒绝，否则将 "env": "prod" 标签添加到容器。
对于 CREATE Pod 请求，盲目地添加一个名为 foo-sidecar 的边车容器，而未查看 Pod 中是否已经有 foo-sidecar 容器。

在上述第一种情况下，重新调用该 Webhook 可能导致同一个边车容器多次注入到 Pod 中，而且每次使用不同的容器名称。类似地，如果 Sidecar 已存在于用户提供的 Pod 中，则 Webhook 可能注入重复的容器。

在上述第二种情况下，重新调用 Webhook 将导致 Webhook 自身输出失败。

在上述第三种情况下，重新调用 Webhook 将导致 Pod 规约中的容器重复，从而使请求无效并被 API 服务器拒绝。

拦截对象的所有版本

建议通过将 .webhooks[].matchPolicy 设置为 Equivalent，以确保准入 Webhooks 始终拦截对象的所有版本。建议准入 Webhooks 应该更偏向注册资源的稳定版本。如果无法拦截对象的所有版本，可能会导致准入策略未再某些版本的请求上执行。有关示例，请参见匹配请求：matchPolicy。

可用性

建议准入 Webhook 尽快完成执行（时长通常是毫秒级），因为它们会增加 API 请求的延迟。建议对 Webhook 使用较小的超时值。有关更多详细信息，请参见超时。

建议准入 Webhook 应该采用某种形式的负载均衡机制，以提供高可用性和高性能。如果集群中正在运行 Webhook，则可以在服务后面运行多个 Webhook 后端，以利用该服务支持的负载均衡。

确保看到对象的最终状态

如果某准入 Webhook 需要保证自己能够看到对象的最终状态以实施策略，则应该使用一个验证性质的 Webhook，因为可以通过变更性质的 Webhook 看到对象后对其进行修改。

例如，一个变更性质的准入 Webhook 被配置为在每个 CREATE Pod 请求中注入一个名称为 "foo-sidecar" 的边车容器。

如果必须存在边车容器，则还应配置一个验证性质的准入 Webhook 以拦截 CREATE Pod 请求，并验证要创建的对象中是否存在具有预期配置的名称为 "foo-sidecar" 的容器。

避免自托管的 Webhooks 中出现死锁

如果集群内的 Webhook 配置能够拦截启动其自己的 Pod 所需的资源，则该 Webhook 可能导致其自身部署时发生死锁。

例如，某变更性质的准入 Webhook 配置为仅当 Pod 中设置了某个标签（例如 "env": "prod"）时，才接受 CREATE Pod 请求。 Webhook 服务器在未设置 "env" 标签的 Deployment 中运行。当运行 Webhook 服务器的容器的节点运行不正常时，Webhook 部署尝试将容器重新调度到另一个节点。但是，由于未设置 "env" 标签，因此请求将被现有的 Webhook 服务器拒绝，并且调度迁移不会发生。

建议使用 namespaceSelector 排除 Webhook 所在的名字空间。

副作用

建议准入 Webhook 应尽可能避免副作用，这意味着该准入 Webhook 仅对发送给他们的 AdmissionReview 的内容起作用，并且不要进行额外更改。如果 Webhook 没有任何副作用，则 .webhooks[].sideEffects 字段应设置为 None。

如果在准入执行期间存在副作用，则应在处理 dryRun 为 true 的 AdmissionReview 对象时避免产生副作用，并且其 .webhooks[].sideEffects 字段应设置为 NoneOnDryRun。更多详细信息，请参见副作用。

避免对 kube-system 名字空间进行操作

kube-system 名字空间包含由 Kubernetes 系统创建的对象，例如用于控制平面组件的服务账号，诸如 kube-dns 之类的 Pod 等。意外更改或拒绝 kube-system 名字空间中的请求可能会导致控制平面组件停止运行或者导致未知行为发生。如果你的准入 Webhook 不想修改 Kubernetes 控制平面的行为，请使用 namespaceSelector 避免拦截 kube-system 名字空间。

最后修改 December 11, 2024 at 10:26 PM PST: Merge pull request #48983 from chanieljdan/update-release-1.31-hugo.toml (4bd18c4)

你正在查看的文档所针对的是 Kubernetes 版本： v1.31

动态准入控制

什么是准入 Webhook？

说明：

尝试准入 Webhook

先决条件

编写一个准入 Webhook 服务器

部署准入 Webhook 服务

即时配置准入 Webhook

说明：

说明：

说明：

对 API 服务器进行身份认证

Webhook 请求与响应

请求

响应

注意：

Webhook 配置

匹配请求-规则

匹配请求：objectSelector

匹配请求：namespaceSelector

匹配请求：matchPolicy

匹配请求：matchConditions

说明：

调用 Webhook

URL

服务引用

说明：

副作用

超时

再调用策略

失败策略

监控 Admission Webhook

变更性质的 Webhook 审计注解

准入 Webhook 度量值

apiserver 准入 Webhook 拒绝次数

最佳实践和警告

幂等性

幂等 mutating admission Webhook 的示例：

非幂等 mutating admission Webhook 的示例：

拦截对象的所有版本

可用性

确保看到对象的最终状态

避免自托管的 Webhooks 中出现死锁

副作用

避免对 kube-system 名字空间进行操作

反馈

匹配请求：`matchConditions`