4. Gatekeeper 组件架构：Controller Manager、Audit Controller、Webhook Server、Constraint Template 与 Constraint

OPA Gatekeeper 是 Kubernetes 的 可审计、可策略、可扩展 的准入控制与合规核验引擎。其组件架构围绕 策略定义、实时拦截、周期性审计 与 状态管理 四个核心职责展开。理解每个组件的角色与协作关系，是集成资源模型实现基线核验的基础。

4.1 组件全景与协作关系

Gatekeeper 由四个主要组件构成，它们共同实现了从策略注册、实时校验到合规审计的闭环。下图展示了各组件的逻辑架构与数据流。

4.2 Gatekeeper Controller Manager

Controller Manager 是 Gatekeeper 的 核心协调器，负责管理所有 CRD 资源的生命周期。它运行在 gatekeeper-controller-manager Pod 中，包含多个子控制器。

4.3 Webhook Server

Webhook Server 是 Gatekeeper 的 实时准入拦截器。它作为 Kubernetes ValidatingAdmissionWebhook 注册，在资源创建、更新、删除时被 API Server 调用。

• 工作流程：
  1. API Server 将准入请求（AdmissionReview）发送到 Webhook Server 的 /v1/admit 端点。
  2. Webhook Server 提取请求中的资源对象（Object）和旧对象（OldObject）。
  3. 将请求数据注入 OPA 引擎，执行所有匹配的 Constraint 策略。
  4. 返回 allowed: true/false 及拒绝消息。
• 超时与容错：默认超时 3 秒；超时或不可用时，API Server 根据 failurePolicy（Fail/Ignore）决定是否放行。
• TLS 安全：Webhook Server 使用 TLS 证书与 API Server 通信，证书由 Gatekeeper 自带的证书管理器自动轮换。

4.4 Audit Controller

Audit Controller 是 Gatekeeper 的 合规审计引擎，负责对集群中 已有资源 进行周期性策略核验。它弥补了 Webhook 只拦截实时请求的不足，确保历史资源也符合基线要求。

4.5 Constraint Template

Constraint Template 是 Gatekeeper 的 策略模板，它是一个 Kubernetes CRD，定义了策略的 逻辑结构 和 Rego 代码。用户通过编写 ConstraintTemplate 来声明一类策略规则。

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredLabels          # 生成的 Constraint CRD 名称
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:
              type: array
              items:
                type: string
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8srequiredlabels

        violation[{"msg": msg}] {
          input.review.object.metadata.labels == null
          msg := "资源必须包含标签"
        }

        violation[{"msg": msg}] {
          required := input.parameters.labels[_]
          not input.review.object.metadata.labels[required]
          msg := sprintf("缺少必要标签: %v", [required])
        }

• CRD 生成：每个 ConstraintTemplate 会自动生成一个同名的 CRD（如 K8sRequiredLabels），用户通过创建该 CRD 的实例来应用策略。
• Rego 策略：violation 规则返回违规消息；input.parameters 接收 Constraint 传入的参数。
• 版本管理：更新 ConstraintTemplate 时，Controller Manager 会重新编译 Rego 并更新所有关联的 Constraint。

4.6 Constraint

Constraint 是 ConstraintTemplate 的 具体实例，它提供了策略的 参数值 和 匹配范围。一个 ConstraintTemplate 可以被实例化为多个 Constraint，每个 Constraint 针对不同的资源或命名空间。

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: require-labels-prod
spec:
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Pod"]
    namespaces: ["production"]
  parameters:
    labels:
      - "app"
      - "env"
      - "owner"

4.7 组件协作流程总结

下图展示了从策略定义到审计结果输出的完整协作流程，帮助理解各组件在基线核验中的具体角色。