📚 课程目录第4章准入策略（Admission Policy）基础

4. 准入策略（Admission Policy）基础：Admission Controller、ValidatingWebhookConfiguration 与 MutatingWebhookConfiguration

在 Kubernetes 多集群环境中，准入策略是保障集群安全与合规的第一道防线。本章将系统讲解 Admission Controller 的工作原理、ValidatingWebhookConfiguration 与 MutatingWebhookConfiguration 的核心差异，以及它们在 Kustomize 多集群场景下的典型故障模式。

4.1 什么是 Admission Controller？

Admission Controller（准入控制器）是 Kubernetes API Server 中的一个关键组件，它在请求经过认证（Authentication）和授权（Authorization）之后、对象被持久化到 etcd 之前，拦截并处理 API 请求。准入控制器可以验证、修改甚至拒绝请求。

关键位置：Admission Controller 位于认证与授权之后、对象持久化之前，是 API 请求进入集群前的最后一道可编程防线。

Kubernetes 内置了多种 Admission Controller，例如 NamespaceLifecycle、LimitRanger、ResourceQuota 等。但更灵活的方式是通过 Webhook 机制动态扩展准入逻辑，即 ValidatingAdmissionWebhook 和 MutatingAdmissionWebhook。

4.2 ValidatingWebhookConfiguration 与 MutatingWebhookConfiguration

Webhook 类型的准入控制器允许集群管理员通过外部 HTTP 回调（Webhook）来扩展准入逻辑。Kubernetes 通过两个 CRD 资源来配置这些 Webhook：

特性	ValidatingWebhookConfiguration	MutatingWebhookConfiguration
执行顺序	在 Mutating Webhook 之后执行	在 Validating Webhook 之前执行
主要功能	验证请求对象是否符合策略，拒绝不合规请求	修改请求对象（注入 sidecar、设置默认值等）
响应类型	`Allowed: true/false` + 拒绝原因	`Allowed: true` + `Patch`（JSON Patch）
典型场景	安全检查、资源配额校验、命名空间隔离	自动注入 Istio sidecar、添加标签/注解
失败策略	`Fail` 或 `Ignore`	`Fail` 或 `Ignore`

执行顺序陷阱：Mutating Webhook 先执行，Validating Webhook 后执行。如果 Mutating Webhook 修改了对象，Validating Webhook 看到的是修改后的版本。在多集群场景中，这种顺序可能导致不同集群的 Webhook 行为不一致，从而引发故障。

4.3 Webhook 配置的核心字段

无论是 Validating 还是 Mutating Webhook，其配置结构基本一致。以下是一个典型的 ValidatingWebhookConfiguration 示例：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "pod-policy.example.com"
webhooks:
- name: "pod-policy.example.com"
  clientConfig:
    service:
      namespace: "webhook-system"
      name: "webhook-service"
      path: "/validate"
    caBundle: "LS0tLS1CRUdJTiBDRV...=="  # base64 编码的 CA 证书
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
    scope: "Namespaced"
  failurePolicy: Fail
  matchPolicy: Equivalent
  sideEffects: None
  timeoutSeconds: 10
  admissionReviewVersions: ["v1"]

关键字段说明：

clientConfig：Webhook 服务器的连接信息，包括 Service 地址和 CA 证书。
rules：定义哪些资源操作会触发 Webhook 调用。
failurePolicy：当 Webhook 服务器不可达时的行为，Fail 会拒绝请求，Ignore 会跳过。
sideEffects：Webhook 调用是否产生副作用，推荐设置为 None。
timeoutSeconds：Webhook 调用超时时间，默认 10 秒。

4.4 多集群场景下的典型故障模式

在 Kustomize 管理多集群配置时，Webhook 配置容易引发以下故障：

CA 证书不匹配：不同集群的 CA 证书不同，导致 Webhook 调用失败。
Service 不可达：Webhook 服务部署在特定集群，其他集群无法访问。
资源版本差异：不同集群的 Kubernetes 版本不同，导致 admissionReviewVersions 不兼容。
Webhook 死锁：Webhook 配置本身触发 Webhook 调用，形成循环依赖。
Kustomize 覆盖冲突：多个 overlay 同时修改 Webhook 配置，导致预期行为不一致。

4.5 故障排查要点

当 Webhook 准入策略出现故障时，建议按以下步骤排查：

步骤	检查项	命令/方法
1	Webhook 配置是否生效	`kubectl get validatingwebhookconfiguration`
2	Webhook 服务是否正常运行	`kubectl get pods -n webhook-system`
3	CA 证书是否匹配	对比 `clientConfig.caBundle` 与服务端证书
4	API 版本兼容性	检查 `admissionReviewVersions` 是否被集群支持
5	Kustomize 覆盖结果	`kustomize build` 查看最终 YAML

  最佳实践：在多集群场景下，建议为每个集群独立管理 Webhook 配置，避免跨集群引用。使用 Kustomize 时，通过 patches 或 components 按集群差异化配置 CA 证书和 Service 地址。