4. Admission Webhook 机制：Mutating 与 Validating Webhook、Webhook 配置与工作原理

Admission Webhook 是 Kubernetes API Server 在对象持久化之前调用的 HTTP 回调机制，是 OPA/Kyverno 等策略引擎实现资源变更校验与自动修改的核心通道。本章深入解析 Mutating 与 Validating 两种 Webhook 的职责差异、配置清单结构以及请求-响应生命周期。

4.1 Mutating 与 Validating Webhook 职责对比

4.2 Webhook 配置清单结构

Kubernetes 通过 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 两种 CRD 资源注册 Webhook。以下是一个典型的 Validating Webhook 配置示例：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "opa-validating-webhook"
webhooks:
- name: "validate.opa.example.com"
  clientConfig:
    service:
      namespace: "opa-system"
      name: "opa-webhook-service"
      path: "/v1/admit"
    caBundle: "LS0tLS1CRUdJTiBDRV...=="
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["*"]
    apiVersions: ["*"]
    resources: ["pods", "deployments"]
  failurePolicy: Fail
  matchPolicy: Equivalent
  sideEffects: None
  timeoutSeconds: 5
  admissionReviewVersions: ["v1"]
  namespaceSelector:
    matchExpressions:
    - key: "admission-webhook.opa.io/exclude"
      operator: "DoesNotExist"

4.3 Webhook 工作原理与请求-响应生命周期

当用户通过 kubectl 或 API 调用创建/更新资源时，API Server 在对象持久化到 etcd 之前触发 Admission Webhook 链。下图展示了完整的请求处理流程：

4.4 AdmissionReview 请求与响应结构

API Server 将用户请求封装为 AdmissionReview 对象发送给 Webhook 服务。Webhook 必须解析该对象并返回包含 allowed 字段的响应。

// 请求结构（Webhook 接收）
{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "request": {
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
    "kind": {"group":"","version":"v1","kind":"Pod"},
    "resource": {"group":"","version":"v1","resource":"pods"},
    "namespace": "default",
    "operation": "CREATE",
    "object": { ... },          // 用户提交的完整对象
    "oldObject": null,          // UPDATE/DELETE 时存在
    "dryRun": false
  }
}

// 响应结构（Webhook 返回）
{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
    "allowed": true,            // false 表示拒绝
    "status": {
      "code": 200,
      "message": "allowed by OPA policy"
    },
    "patch": "W3sib3AiOiJhZGQiLCJwYXRoIjoiL3NwZWMvY29udGFpbmVycy8wL3NlY3VyaXR5Q29udGV4dC9jYXBhYmlsaXRpZXMiLCJ2YWx1ZSI6WyJORVdfQ0FQIiwgS0lMTF9QUk9DRVNTIl19XQ==",
    "patchType": "JSONPatch"
  }
}

4.5 Webhook 链执行顺序与并发模型

Kubernetes 1.16+ 支持 Webhook 的 reinvocationPolicy 字段，控制 Mutating Webhook 是否在对象被其他 Webhook 修改后再次调用。Validating Webhook 始终在 Mutating Webhook 之后执行。

4.6 证书管理与 TLS 配置

所有 Admission Webhook 必须使用 TLS 通信。API Server 作为客户端，Webhook 服务作为服务端。证书管理是 Webhook 稳定运行的基础。

# 使用 cert-manager 自动签发证书示例
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: opa-webhook-cert
  namespace: opa-system
spec:
  secretName: opa-webhook-tls
  dnsNames:
  - "opa-webhook-service.opa-system.svc"
  - "opa-webhook-service.opa-system.svc.cluster.local"
  issuerRef:
    name: selfsigned-issuer
    kind: Issuer

4.7 故障排查与调试命令

• 查看 Webhook 配置：kubectl get validatingwebhookconfiguration -o yaml
• 检查 Webhook 日志：kubectl logs -n opa-system deployment/opa-webhook -f
• 模拟 AdmissionReview：使用 kubectl create --dry-run=server -f pod.yaml 触发 Webhook 但不持久化
• 测试 TLS 连通性：kubectl run -it --rm debug --image=curlimages/curl -- sh -c "curl -k https://opa-webhook-service.opa-system.svc:443/v1/admit"
• 查看 API Server 审计日志：kubectl logs -n kube-system kube-apiserver-<node> --tail=100 | grep -i webhook