4. Webhook 配置详解：MutatingWebhookConfiguration 与 ValidatingWebhookConfiguration 的 YAML 结构、关键字段

在 Kubernetes 中，准入控制 Webhook 的注册与配置完全通过两种 API 资源完成：MutatingWebhookConfiguration（变更准入）和 ValidatingWebhookConfiguration（验证准入）。两者的 YAML 结构高度相似，但核心语义不同。本章将深入拆解其字段层级、配置要点及常见陷阱，为后续接口测试中的 Webhook 模拟与拦截提供精确的配置依据。

4.1 两种 Webhook 配置的核心差异

4.2 YAML 结构全景：顶层字段与嵌套层级

以下是一个典型的 MutatingWebhookConfiguration 完整 YAML 示例，ValidatingWebhookConfiguration 结构与之相同，仅 kind 不同：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: "pod-annotation-injector.example.com"
webhooks:
- name: "annotate-pods.example.com"
  clientConfig:
    url: "https://webhook-service.namespace.svc:443/mutate"
    caBundle: "LS0tLS1CRUdJTiBDRV...=="
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
    scope: "Namespaced"
  failurePolicy: Fail
  matchPolicy: Equivalent
  sideEffects: None
  timeoutSeconds: 10
  reinvocationPolicy: IfNeeded
  admissionReviewVersions: ["v1"]

4.3 关键字段深度解析

4.3.1 clientConfig：Webhook 服务连接配置

clientConfig 定义了 API Server 如何调用你的 Webhook 服务。有两种配置方式：

• url 方式：直接指定 HTTPS 端点，适合外部服务或调试。
• service 方式：引用集群内 Service，推荐生产使用。

4.3.2 rules：触发规则定义

rules 是一个数组，每个规则定义了哪些操作、资源、API 组会触发 Webhook 调用。规则之间是 OR 关系，只要匹配任意一条规则即触发。

4.3.3 failurePolicy：失败处理策略

failurePolicy 决定了当 Webhook 调用失败（网络超时、证书错误、服务不可用）时，API Server 的行为：

4.4 辅助字段速查表

4.5 Webhook 配置与 API Server 交互流程

下图展示了 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 在准入链中的位置及配置字段的生效顺序：

4.6 配置示例：用于存储版本漂移校准的 Webhook

以下是一个专门用于拦截和校准存储版本漂移的 ValidatingWebhookConfiguration 示例，它会在 Pod 创建或更新时校验其 metadata.annotations 中的版本号是否与集群期望版本一致：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "version-drift-validator.example.com"
webhooks:
- name: "validate-version.example.com"
  clientConfig:
    service:
      namespace: "webhook-system"
      name: "version-validator-svc"
      path: "/validate-version"
      port: 443
    caBundle: "LS0tLS1CRUdJTiBDRV...=="
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
    scope: "Namespaced"
  failurePolicy: Fail
  matchPolicy: Equivalent
  sideEffects: None
  timeoutSeconds: 5
  admissionReviewVersions: ["v1"]
  objectSelector:
    matchLabels:
      app: "version-tracked"

4.7 配置验证与常见错误