📚 课程目录第3章 Gatekeeper 架构解析

3. Gatekeeper 架构解析：Admission Webhook、Constraint Framework、数据复制

理解 Gatekeeper 的架构是编写高效约束规则和排查问题的前提。Gatekeeper 并非一个单体组件，而是由 Admission Webhook、Constraint Framework 和 数据复制（Replicator） 三大核心模块构成的协同系统。本章将逐一拆解这些模块的职责与交互流程。

3.1 整体架构概览

Gatekeeper 以 可变更的准入 Webhook（Mutating Admission Webhook） 和 验证准入 Webhook（Validating Admission Webhook） 的形式注册到 Kubernetes API Server。当资源创建、更新或删除请求到达 API Server 时，Gatekeeper 会拦截请求，并根据用户定义的约束策略进行校验或变更。

3.2 Admission Webhook：策略执行的入口

Admission Webhook 是 Gatekeeper 与 Kubernetes API Server 之间的桥梁。它负责拦截资源请求，并将其转发给内部的 OPA 引擎进行策略评估。

3.2.1 两种 Webhook 模式

Webhook 类型	触发时机	Gatekeeper 用途	典型场景
ValidatingWebhookConfiguration	资源持久化之前	验证资源是否符合约束规则	禁止特权容器、强制标签
MutatingWebhookConfiguration	资源持久化之前（先于验证）	自动修改资源以符合约束	自动注入 Sidecar、设置默认值

实践建议： 大多数安全基线巡检场景使用 ValidatingWebhookConfiguration 即可。仅当需要自动修复不合规资源（如自动添加 Pod 安全上下文）时，才启用 MutatingWebhookConfiguration。

3.2.2 Webhook 配置关键参数

在部署 Gatekeeper 时，Kubernetes 会自动创建 Webhook 配置。以下参数直接影响策略执行范围与性能：

failurePolicy：当 Webhook 不可用时，API Server 的行为。推荐设置为 Fail（严格模式）或 Ignore（宽松模式）。
matchPolicy：决定哪些资源触发 Webhook。支持 Exact（精确匹配）和 Equivalent（等效匹配，推荐）。
objectSelector：基于资源标签选择器过滤请求，减少不必要的 Webhook 调用。
timeoutSeconds：Webhook 超时时间，默认 30 秒。复杂策略可适当调高，但建议控制在 10 秒以内。

3.3 Constraint Framework：策略定义与执行引擎

Constraint Framework 是 Gatekeeper 的核心，它基于 OPA（Open Policy Agent） 的 Rego 语言，提供了一套声明式的策略定义模型。该模型由三个层次组成：

3.3.1 三层策略模型

层次	Kubernetes 资源类型	职责	示例
Template（约束模板）	`ConstraintTemplate`	定义 Rego 策略逻辑和参数 schema	检查容器是否允许特权模式
Constraint（约束实例）	自定义资源（CRD）	实例化模板，传入具体参数和匹配范围	禁止所有 Namespace 使用特权容器
Data（集群数据）	内置缓存 + 外部数据	提供策略评估所需的集群状态	当前 Pod、Namespace、Service 列表

3.3.2 Rego 策略执行流程

当 Webhook 接收到请求后，Constraint Framework 会执行以下步骤：

解析请求：提取资源类型、名称、Namespace、Spec 等字段。
匹配约束：遍历所有 Constraint 实例，筛选出匹配当前资源类型的约束。
执行 Rego：将请求数据与集群缓存数据注入 OPA 引擎，运行 Rego 规则。
生成决策：Rego 规则返回 allow（通过）或 deny（拒绝），并附带拒绝原因。
返回响应：将决策结果封装为 AdmissionReview 响应，返回给 API Server。

  关键概念： Rego 规则中的 violation 块是 Gatekeeper 特有的约定。当 violation 块中的条件为真时，表示资源违反约束，Gatekeeper 会拒绝该请求。

3.4 数据复制（Replicator）：策略决策的数据基础

OPA 引擎在评估策略时，需要访问集群的实时状态（如当前 Pod 列表、Namespace 标签等）。Gatekeeper 通过 数据复制（Replicator） 模块，将集群中的资源数据同步到 OPA 的缓存中，避免每次策略评估都直接调用 API Server。

3.4.1 数据复制的工作原理

监听机制：Replicator 使用 Kubernetes Informer 监听指定资源的变化（如 Pod、Namespace、Service）。
缓存存储：将监听到的资源数据以 JSON 格式存储在 OPA 的 data 命名空间中，供 Rego 规则查询。
增量更新：仅同步变化的部分，减少网络和计算开销。
配置方式：通过 ConfigMap 或 Gatekeeper 配置 指定需要复制的资源类型。

3.4.2 配置数据复制示例

以下配置告诉 Gatekeeper 复制所有 Namespace 和 Pod 数据：

apiVersion: config.gatekeeper.sh/v1alpha1
kind: Config
metadata:
  name: config
  namespace: gatekeeper-system
spec:
  sync:
    syncOnly:
      - group: ""
        version: "v1"
        kind: "Namespace"
      - group: ""
        version: "v1"
        kind: "Pod"

性能注意事项： 复制过多资源类型（如所有 Secrets、ConfigMaps）会显著增加 Gatekeeper 的内存占用和网络负载。建议仅复制策略评估所必需的资源。对于大型集群（>1000 节点），可考虑使用 --disable-opa-builtin 参数禁用不必要的内置函数。

3.4.3 数据复制与策略性能的关系

场景	复制策略	性能影响	建议
仅检查当前请求资源	不复制任何资源	低延迟，低内存	适用于简单标签校验
需要跨资源关联检查	复制 Namespace + Pod	中等延迟，中等内存	适用于检查 Pod 是否在允许的 Namespace 中
需要全局资源清单	复制所有 Namespace、Pod、Service、Deployment	高延迟，高内存	适用于复杂合规审计，需评估集群规模

3.5 模块间协作总结

Gatekeeper 的三个核心模块通过以下方式协同工作：

Admission Webhook 作为入口，接收 API Server 的请求并返回决策。
Constraint Framework 作为策略引擎，解析 ConstraintTemplate 和 Constraint，执行 Rego 规则。
数据复制（Replicator） 作为数据层，为策略引擎提供集群实时状态。