📚 课程目录第3章 Kubernetes 准入控制基础

Kubernetes 准入控制基础：Admission Controller 类型、Mutating vs Validating Webhook、Webhook 配置详解

在 Kubernetes 集群中，所有对 API Server 的请求（如创建 Pod、更新 Deployment）在通过认证和授权后，会进入一个关键的中间层——准入控制（Admission Control）。这是请求被持久化到 etcd 之前的最后一道防线，也是 OPA Gatekeeper 这类策略引擎发挥作用的核心位置。

1. 什么是 Admission Controller？

Admission Controller 是一段拦截并处理 API 请求的插件代码，它位于认证（Authentication）和授权（Authorization）之后，对象持久化（etcd）之前。根据其行为，分为两类：

类型	作用时机	典型用途
Mutating	先执行，可修改请求对象	注入 Sidecar、设置默认值、修正镜像地址
Validating	后执行，只能校验不可修改	策略检查、安全合规、资源配额验证

关键顺序： 对于同一个请求，所有 Mutating Admission Controller 会先按顺序执行，然后所有 Validating Admission Controller 再执行。如果 Mutating 阶段修改了对象，Validating 阶段看到的是修改后的版本。

2. Mutating vs Validating Webhook

Kubernetes 内置了多种 Admission Controller（如 NamespaceLifecycle、LimitRanger），但更灵活的方式是通过 Dynamic Admission Control 注册外部 Webhook。OPA Gatekeeper 正是通过这种方式接入集群。

MutatingAdmissionWebhook：允许外部 HTTP 回调修改传入的对象。例如，自动为所有 Pod 添加 imagePullPolicy: Always 或注入 OPA 边车代理。
ValidatingAdmissionWebhook：只允许外部 HTTP 回调决定接受或拒绝请求。Gatekeeper 的 Constraint 校验通常使用此类型。

  OPA Gatekeeper 的典型模式： 使用 ValidatingAdmissionWebhook 拒绝违反策略的请求，同时使用 MutatingAdmissionWebhook 自动修正镜像拉取凭证或添加标签。

3. Webhook 配置详解

Webhook 的配置通过 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 资源对象定义。以下是一个典型的 ValidatingWebhookConfiguration 示例，用于拦截 Pod 创建请求：

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: "gatekeeper-validating-webhook"
webhooks:
- name: "gatekeeper.sh"
  clientConfig:
    service:
      name: "gatekeeper-webhook-service"
      namespace: "gatekeeper-system"
      path: "/v1/admit"
    caBundle: "LS0tLS1CRUdJTiBDRV...=="  # 集群 CA 证书
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
    scope: "Namespaced"
  admissionReviewVersions: ["v1"]
  sideEffects: None
  timeoutSeconds: 5
  failurePolicy: Fail
  matchPolicy: Equivalent
  namespaceSelector:
    matchExpressions:
    - key: "admission.gatekeeper.sh/ignore"
      operator: "DoesNotExist"
  objectSelector: {}
  reinvocationPolicy: Never

配置字段解析

字段	说明	推荐值
`clientConfig`	Webhook 服务的地址（Service 或 URL）及 CA 证书	使用集群内 Service 名称
`rules`	匹配哪些操作、资源、API 组	精确匹配，避免拦截无关请求
`failurePolicy`	Webhook 不可用时的行为：`Fail` 或 `Ignore`	策略场景用 `Fail`，非关键场景用 `Ignore`
`sideEffects`	Webhook 是否产生副作用（如修改集群状态）	通常设为 `None`
`timeoutSeconds`	Webhook 调用超时时间	5-10 秒，避免阻塞 API Server
`namespaceSelector`	按命名空间标签过滤请求	排除系统命名空间，避免自举问题

避坑指南： 如果 failurePolicy 设为 Fail，而 Webhook 服务不可用，整个集群的 Pod 创建都会被阻塞。建议在调试阶段使用 Ignore，生产环境确保 Webhook 高可用。

4. 请求处理流程（SVG 图）

下图展示了从用户发起请求到对象持久化的完整准入控制链路，以及 Mutating 和 Validating Webhook 的介入位置：

5. 配置最佳实践

精确匹配规则：在 rules 中尽量缩小匹配范围，避免拦截 ConfigMap、Secret 等高频资源，减少 API Server 负载。
使用 namespaceSelector：排除 kube-system、gatekeeper-system 等系统命名空间，防止 Webhook 自举导致集群不可用。
设置合理的 timeoutSeconds：建议 5-10 秒，超时后按 failurePolicy 处理。
reinvocationPolicy：对于 Mutating Webhook，如果后续有其他 Webhook 再次修改对象，是否重新调用。通常设为 Never 避免循环。

  Gatekeeper 的 Webhook 配置特点： Gatekeeper 会自动生成 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration，但你可以通过 Helm values 或直接修改配置来调整 failurePolicy、namespaceSelector 等参数，以适配不同环境的安全要求。