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

4. 准入控制基础：Kubernetes 准入控制器

Kubernetes 准入控制器（Admission Controller）是 API Server 请求链路上的关键拦截与校验组件。它位于请求经过认证（Authentication）和授权（Authorization）之后、对象持久化到 etcd 之前。准入控制器可以修改（Mutate）或验证（Validate）传入的 API 对象，是集群安全策略、资源配额、默认值注入等能力的核心实现机制。

4.1 准入控制器的位置与作用

下图展示了 Kubernetes API 请求的完整处理流程，突出准入控制阶段在请求链路中的位置：

核心要点：准入控制器是 API Server 插件化的扩展点。Kubernetes 内置了多种准入控制器（如 NamespaceLifecycle、LimitRanger、ResourceQuota），同时也支持通过 Webhook 机制引入自定义的准入逻辑。

4.2 准入控制器的两种类型

Kubernetes 准入控制器分为两大类：内置（Built-in）和动态（Dynamic）。动态准入控制器通过 Webhook 配置实现，是 CNI 插件与集群安全策略集成的核心通道。

类型	配置方式	典型场景	是否可自定义
内置准入控制器	kube-apiserver 启动参数 `--enable-admission-plugins`	资源配额、命名空间生命周期、Pod 安全策略	否（由 Kubernetes 发行版决定）
动态准入控制器	`MutatingWebhookConfiguration` / `ValidatingWebhookConfiguration` 资源对象	CNI 网络策略注入、sidecar 注入、自定义资源校验	是（通过 Webhook 服务实现）

4.3 Mutating 与 Validating Webhook 的区别

动态准入控制器通过 Webhook 机制与外部服务交互。根据 Webhook 在请求链路上的作用阶段，分为 MutatingWebhook 和 ValidatingWebhook 两种类型。它们的核心区别如下：

对比维度	MutatingWebhook	ValidatingWebhook
执行顺序	先执行（在对象持久化之前）	后执行（在 Mutating 之后）
主要功能	修改（Mutate）API 对象内容	验证（Validate）API 对象是否满足约束
典型操作	注入默认值、添加标签/注解、设置资源限制	检查字段合法性、验证安全策略、拒绝非法请求
响应类型	`JSON Patch` 格式的修改操作	`allowed: true/false` 及拒绝原因
幂等性要求	必须幂等（可能被多次调用）	无特殊要求
CNI 场景示例	为 Pod 注入网络注解、设置默认网络策略	校验 Pod 网络配置是否合规、拒绝非法网络策略

4.4 Webhook 配置示例

以下是一个典型的 MutatingWebhookConfiguration 配置，用于 CNI 插件在 Pod 创建时注入网络注解：

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: cni-network-injector
webhooks:
  - name: inject.cni.example.com
    clientConfig:
      service:
        name: cni-webhook-service
        namespace: kube-system
        path: /mutate
      caBundle: <base64-encoded-ca-cert>
    rules:
      - operations: ["CREATE"]
        apiGroups: [""]
        apiVersions: ["v1"]
        resources: ["pods"]
    admissionReviewVersions: ["v1"]
    sideEffects: None
    timeoutSeconds: 10
    reinvocationPolicy: IfNeeded
    objectSelector:
      matchLabels:
        cni-inject: "enabled"

  配置要点：
  rules 字段定义了 Webhook 拦截的资源范围（操作、API 组、版本、资源类型）
objectSelector 通过标签选择器精确控制哪些对象需要触发 Webhook，减少不必要的调用
reinvocationPolicy 控制是否允许后续 Mutating Webhook 再次修改本 Webhook 已修改的对象
sideEffects 必须声明为 None 或 NoneOnDryRun，确保 Webhook 无副作用

4.5 执行顺序与失败策略

Webhook 的执行顺序和失败处理策略直接影响集群的稳定性和可用性：

执行顺序：所有 MutatingWebhook 按配置顺序执行 → 对象被修改 → 所有 ValidatingWebhook 按配置顺序执行 → 最终对象持久化到 etcd
失败策略（failurePolicy）：
- Fail：Webhook 调用失败时，拒绝整个 API 请求（默认值，适用于严格校验场景）
- Ignore：Webhook 调用失败时，跳过该 Webhook 继续处理（适用于非关键性注入）
超时控制：timeoutSeconds 默认 10 秒，超过时限视为失败，按 failurePolicy 处理

生产环境注意事项：Webhook 服务的高可用性至关重要。如果 failurePolicy 设置为 Fail，Webhook 服务宕机会导致集群内所有匹配规则的资源创建/更新操作被拒绝。建议：

为 Webhook 服务部署多个副本，并配置 Pod 反亲和性
设置合理的 timeoutSeconds（通常 3-5 秒）
使用 objectSelector 缩小 Webhook 的触发范围

4.6 在 CNI 场景中的典型应用

CNI 插件利用准入控制 Webhook 实现网络策略的自动化注入和校验：

CNI 场景	Webhook 类型	具体操作
Pod 网络注解注入	Mutating	为 Pod 添加 `k8s.v1.cni.cncf.io/networks` 注解，指定附加网络
默认网络策略注入	Mutating	为新建 Namespace 自动创建默认的 `NetworkPolicy` 资源
网络配置合规校验	Validating	检查 Pod 是否使用了允许的网络插件、IP 池是否在授权范围内
多网络接口验证	Validating	确保 Pod 声明的附加网络接口数量不超过集群限制

通过合理组合 Mutating 和 Validating Webhook，CNI 插件可以在不修改 kubelet 或容器运行时的情况下，实现灵活的网络策略管控，这也是 Kubernetes 网络生态中“声明式网络配置”理念的核心实现方式。