MutatingWebhookConfiguration

MutatingWebhookConfiguration 描述了准入 Webhook 的配置，该 Webhook 可以接受或拒绝对象，并可能对其进行修改。

apiVersion: admissionregistration.k8s.io/v1

import "k8s.io/api/admissionregistration/v1"

MutatingWebhookConfiguration

MutatingWebhookConfiguration 描述了准入 Webhook 的配置，该 Webhook 可以接受或拒绝对象，并可能对其进行修改。

  • apiVersion: admissionregistration.k8s.io/v1

  • kind: MutatingWebhookConfiguration

  • metadata (ObjectMeta)

    标准对象元数据；更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata。

  • webhooks ([]MutatingWebhook)

    合并策略：按键 name 合并

    Map：合并时将保留键名为唯一值

    Webhooks 是 Webhook 及其受影响资源和操作的列表。

    MutatingWebhook 描述了一个准入 Webhook 及其适用的资源和操作。

    • webhooks.admissionReviewVersions ([]string)，必需

      原子性：合并时将被替换

      AdmissionReviewVersions 是 Webhook 期望的优先 AdmissionReview 版本有序列表。API 服务器将尝试使用列表中它支持的第一个版本。如果 API 服务器不支持列表中指定的任何版本，则该对象的验证将失败。如果持久化的 Webhook 配置指定了允许的版本但不包含 API 服务器知道的任何版本，则对 Webhook 的调用将失败并受故障策略约束。

    • webhooks.clientConfig (WebhookClientConfig)，必需

      ClientConfig 定义了如何与 Webhook 通信。必需。

      WebhookClientConfig 包含与 Webhook 进行 TLS 连接的信息

      • webhooks.clientConfig.caBundle ([]byte)

        caBundle 是一个 PEM 编码的 CA 证书包，用于验证 Webhook 的服务器证书。如果未指定，则使用 apiserver 上的系统信任根证书。

      • webhooks.clientConfig.service (ServiceReference)

        service 是对此 Webhook 所属服务的引用。必须指定 service 或 url 中的一个。

        如果 Webhook 在集群内运行，则应使用 service。

        ServiceReference 持有对 Service.legacy.k8s.io 的引用

        • webhooks.clientConfig.service.name (string)，必需

          name 是服务的名称。必需。

        • webhooks.clientConfig.service.namespace (string)，必需

          namespace 是服务的命名空间。必需。

        • webhooks.clientConfig.service.path (string)

          path 是可选的 URL 路径，将在对此服务发出的任何请求中发送。

        • webhooks.clientConfig.service.port (int32)

          如果指定，则为托管 Webhook 的 Service 上的端口。为了向后兼容，默认为 443。port 应该是一个有效的端口号（包括 1-65535）。

      • webhooks.clientConfig.url (string)

        url 以标准 URL 格式（scheme://host:port/path）指定 Webhook 的位置。必须且只能指定 url 或 service 中的一个。

        host 不应指向在集群内运行的服务；请改用 service 字段。在某些 apiserver 中（例如 kube-apiserver 无法解析集群内 DNS，因为这会违反分层原则），host 可能通过外部 DNS 解析。host 也可以是 IP 地址。

        请注意，除非你非常小心地在所有运行 apiserver 并可能需要调用此 Webhook 的主机上运行此 Webhook，否则使用 localhost 或 127.0.0.1 作为 host 是有风险的。此类安装可能不可移植，即不容易在新集群中启动。

        Scheme 必须是 "https"；URL 必须以 "https://" 开头。

        路径是可选的，如果存在，可以是 URL 中允许的任何字符串。你可以使用路径向 Webhook 传递任意字符串，例如集群标识符。

        不允许尝试使用用户或基本认证（例如 "user:password@"）。片段 ("#...") 和查询参数 ("?...") 也不允许。

    • webhooks.name (string)，必需

      准入 Webhook 的名称。名称应为完全限定名，例如 imagepolicy.kubernetes.io，其中 "imagepolicy" 是 Webhook 的名称，kubernetes.io 是组织的名称。必需。

    • webhooks.sideEffects (string)，必需

      SideEffects 说明此 Webhook 是否具有副作用。可接受的值为：None, NoneOnDryRun（通过 v1beta1 创建的 Webhook 还可以指定 Some 或 Unknown）。具有副作用的 Webhook 必须实现协调系统，因为请求可能被准入链中的后续步骤拒绝，因此需要撤销副作用。如果具有 dryRun 属性的请求与 sideEffects == Unknown 或 Some 的 Webhook 匹配，则会被自动拒绝。

    • webhooks.failurePolicy (string)

      FailurePolicy 定义了如何处理来自准入端点的无法识别的错误 - 允许的值是 Ignore 或 Fail。默认为 Fail。

    • webhooks.matchConditions ([]MatchCondition)

      合并策略：按键 name 合并

      Map：合并时将保留键名为唯一值

      MatchConditions 是请求发送到此 Webhook 必须满足的条件列表。匹配条件过滤已经由 rules、namespaceSelector 和 objectSelector 匹配的请求。空的 matchConditions 列表匹配所有请求。最多允许 64 个匹配条件。

      精确的匹配逻辑是（按顺序）

      1. 如果任何 matchCondition 求值为 FALSE，则跳过 Webhook。
      2. 如果所有 matchConditions 求值为 TRUE，则调用 Webhook。
      3. 如果任何 matchCondition 求值为错误（但没有一个是 FALSE）
        • 如果 failurePolicy=Fail，拒绝请求
        • 如果 failurePolicy=Ignore，则忽略错误并跳过 Webhook

      MatchCondition 表示请求发送到 Webhook 必须满足的条件。

      • webhooks.matchConditions.expression (string)，必需

        Expression 表示将由 CEL 求值的表达式。必须求值为 bool 类型。CEL 表达式可以访问 AdmissionRequest 和 Authorizer 的内容，组织成 CEL 变量

        'object' - 入站请求中的对象。对于 DELETE 请求，该值为 null。'oldObject' - 现有对象。对于 CREATE 请求，该值为 null。'request' - 准入请求的属性（/pkg/apis/admission/types.go#AdmissionRequest）。'authorizer' - CEL Authorizer。可用于对请求的主体（用户或 ServiceAccount）执行授权检查。参见 https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz。'authorizer.requestResource' - 基于 'authorizer' 并使用请求资源配置的 CEL ResourceCheck。CEL 文档：https://kubernetes.ac.cn/docs/reference/using-api/cel/

        必需。

      • webhooks.matchConditions.name (string)，必需

        Name 是此匹配条件的标识符，用于 MatchConditions 的策略合并，也用于日志记录。一个好的名称应该能描述相关的表达式。名称必须是合格名称，由字母数字字符、'-'、'_' 或 '.' 组成，并且必须以字母数字字符开头和结尾（例如 'MyName'、'my.name' 或 '123-abc'，用于验证的正则表达式为 '([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]'），并可选择加上 DNS 子域前缀和 '/'（例如 'example.com/MyName'）。

        必需。

    • webhooks.matchPolicy (string)

      matchPolicy 定义了如何使用 "rules" 列表匹配入站请求。允许的值为 "Exact" 或 "Equivalent"。

      • Exact：仅当请求与指定规则完全匹配时才匹配。例如，如果部署可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 进行修改，但 "rules" 只包含 apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]，则发送到 apps/v1beta1 或 extensions/v1beta1 的请求将不会发送到 Webhook。

      • Equivalent：如果请求修改了 rules 中列出的资源，即使是通过其他 API 组或版本进行修改，也会匹配。例如，如果部署可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 进行修改，并且 "rules" 只包含 apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]，则发送到 apps/v1beta1 或 extensions/v1beta1 的请求将被转换为 apps/v1 并发送到 Webhook。

      默认为 "Equivalent"。

    • webhooks.namespaceSelector (LabelSelector)

      NamespaceSelector 根据对象的命名空间是否与选择器匹配来决定是否在对象上运行 Webhook。如果对象本身是命名空间，则根据 object.metadata.labels 进行匹配。如果对象是其他集群范围的资源，则永远不会跳过 Webhook。

      例如，要在其命名空间不关联 "runlevel" 为 "0" 或 "1" 的任何对象上运行 Webhook，你将选择器设置为如下所示："namespaceSelector": { "matchExpressions": [ { "key": "runlevel", "operator": "NotIn", "values": [ "0", "1" ] } ] }

      如果你想只在其命名空间关联 "environment" 为 "prod" 或 "staging" 的任何对象上运行 Webhook，你将选择器设置为如下所示："namespaceSelector": { "matchExpressions": [ { "key": "environment", "operator": "In", "values": [ "prod", "staging" ] } ] }

      有关标签选择器的更多示例，请参见 https://kubernetes.ac.cn/docs/concepts/overview/working-with-objects/labels/。

      默认为空的 LabelSelector，它匹配所有内容。

    • webhooks.objectSelector (LabelSelector)

      ObjectSelector 根据对象是否具有匹配标签来决定是否运行 Webhook。objectSelector 会对照将发送到 Webhook 的 oldObject 和 newObject 进行评估，如果任一对象与选择器匹配，则认为匹配。空对象（创建时的 oldObject 或删除时的 newObject）或无法具有标签的对象（例如 DeploymentRollback 或 PodProxyOptions 对象）不被视为匹配。仅当 Webhook 是选择性加入时才使用对象选择器，因为最终用户可能通过设置标签来跳过准入 Webhook。默认为空的 LabelSelector，它匹配所有内容。

    • webhooks.reinvocationPolicy (string)

      reinvocationPolicy 指示此 Webhook 是否应作为单一准入评估的一部分被多次调用。允许的值为 "Never" 和 "IfNeeded"。

      Never：在单一准入评估中，Webhook 不会被调用超过一次。

      IfNeeded：如果在初始 Webhook 调用后被准入的对象被其他准入插件修改，则此 Webhook 将作为准入评估的一部分至少被额外调用一次。指定此选项的 Webhook 必须是幂等的，能够处理它们之前准入的对象。注意：* 不能保证额外的调用次数恰好为一次。* 如果额外的调用导致对象进一步修改，不能保证 Webhook 会再次被调用。* 使用此选项的 Webhook 可能会被重新排序，以最大限度地减少额外调用的次数。* 要在所有突变保证完成后验证对象，请改用验证准入 Webhook。

      默认为 "Never"。

    • webhooks.rules ([]RuleWithOperations)

      原子性：合并时将被替换

      Rules 描述了 Webhook 关注哪些资源/子资源的哪些操作。如果 Webhook 匹配 任何 Rule，则表示它关注该操作。但是，为了防止 ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 将集群置于完全禁用插件后也无法恢复的状态，它们永远不会在针对 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 对象的准入请求上被调用。

      RuleWithOperations 是 Operations 和 Resources 的元组。建议确保所有元组展开都有效。

      • webhooks.rules.apiGroups ([]string)

        原子性：合并时将被替换

        APIGroups 是资源所属的 API 组。'' 表示所有组。如果存在 ''，切片的长度必须为一。必需。

      • webhooks.rules.apiVersions ([]string)

        原子性：合并时将被替换

        APIVersions 是资源所属的 API 版本。'' 表示所有版本。如果存在 ''，切片的长度必须为一。必需。

      • webhooks.rules.operations ([]string)

        原子性：合并时将被替换

        Operations 是准入钩子关注的操作 - CREATE、UPDATE、DELETE、CONNECT 或 * 表示所有这些操作和任何将来添加的准入操作。如果存在 '*'，切片的长度必须为一。必需。

      • webhooks.rules.resources ([]string)

        原子性：合并时将被替换

        Resources 是此规则适用的资源列表。

        例如：'pods' 表示 Pods。'pods/log' 表示 Pods 的日志子资源。'' 表示所有资源，但不包括子资源。'pods/' 表示 Pods 的所有子资源。'/scale' 表示所有 scale 子资源。'/*' 表示所有资源及其子资源。

        如果存在通配符，验证规则将确保资源之间不重叠。

        根据 enclosing object，子资源可能不被允许。必需。

      • webhooks.rules.scope (string)

        scope 指定此规则的作用域。有效值为 "Cluster"、"Namespaced" 和 ""。 "Cluster" 表示只有集群范围的资源将匹配此规则。Namespace API 对象是集群范围的。"Namespaced" 表示只有命名空间范围的资源将匹配此规则。"" 表示没有作用域限制。子资源匹配其父资源的作用域。默认为 "*"。

    • webhooks.timeoutSeconds (int32)

      TimeoutSeconds 指定此 Webhook 的超时时间。超时后，Webhook 调用将被忽略或 API 调用将根据故障策略失败。超时值必须在 1 到 30 秒之间。默认为 10 秒。

MutatingWebhookConfigurationList

MutatingWebhookConfigurationList 是 MutatingWebhookConfiguration 的列表。

操作

get 读取指定的 MutatingWebhookConfiguration

HTTP 请求

GET /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

  • name (在路径中): string，必需

    MutatingWebhookConfiguration 的名称

  • pretty (在查询参数中): string

    pretty

响应

200 (MutatingWebhookConfiguration): OK

401: 未授权

list 列出或监视 MutatingWebhookConfiguration 类型的对象

HTTP 请求

GET /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

参数

响应

200 (MutatingWebhookConfigurationList): OK

401: 未授权

create 创建 MutatingWebhookConfiguration

HTTP 请求

POST /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

参数

响应

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

202 (MutatingWebhookConfiguration): Accepted

401: 未授权

update 替换指定的 MutatingWebhookConfiguration

HTTP 请求

PUT /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

响应

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

401: 未授权

patch 部分更新指定的 MutatingWebhookConfiguration

HTTP 请求

PATCH /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

  • name (在路径中): string，必需

    MutatingWebhookConfiguration 的名称

  • body: Patch，必需

  • dryRun (在查询参数中): string

    dryRun

  • fieldManager (在查询参数中): string

    fieldManager

  • fieldValidation (在查询参数中): string

    fieldValidation

  • force (在查询参数中): boolean

    force

  • pretty (在查询参数中): string

    pretty

响应

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

401: 未授权

delete 删除 MutatingWebhookConfiguration

HTTP 请求

DELETE /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

参数

响应

200 (Status): OK

202 (Status): Accepted

401: 未授权

deletecollection 删除 MutatingWebhookConfiguration 集合

HTTP 请求

DELETE /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

参数

响应

200 (Status): OK

401: 未授权

本页面自动生成。

如果你打算报告此页面的问题，请在问题描述中提及此页面是自动生成的。修复可能需要在 Kubernetes 项目的其他地方进行。

最后修改时间：2025 年 4 月 9 日下午 6:36 PST：更新 v1.32 的 API 参考文档 (a3b579d035)