4. 迁移适配总览：从 Gatekeeper 到 Kyverno 的映射关系、策略类型对应表、迁移决策树、常见迁移陷阱

从 OPA Gatekeeper 迁移到 Kyverno 并非简单的语法替换，而是策略引擎范式的转变。Gatekeeper 依赖 Rego 查询语言和 AdmissionReview 原语，而 Kyverno 采用声明式 YAML 匹配规则与内置上下文变量。本章提供完整的映射关系、策略类型对应表、迁移决策树以及常见陷阱，帮助团队在迁移过程中避免重复造轮子。

4.1 核心概念映射关系

下表列出 Gatekeeper 与 Kyverno 在架构、资源模型、约束定义、异常处理等维度的直接对应关系：

维度 Gatekeeper (OPA) Kyverno 说明
策略定义 ConstraintTemplate (Rego) ClusterPolicy / Policy (YAML) Kyverno 无需编写 Rego，使用声明式规则
约束实例 Constraint (CRD 实例) ClusterPolicy 中的 rules 数组 Kyverno 将约束实例合并到策略规则中
匹配资源 match 块 + labelSelector match / exclude 块 Kyverno 支持更丰富的匹配条件（名称、命名空间、注解）
变更逻辑 Rego mutate (需自定义) mutate 规则（patchStrategicMerge / patchesJson6902） Kyverno 原生支持资源变更，无需额外编码
验证逻辑 Rego violation 块 validate 规则（pattern / deny / anyPattern） Kyverno 提供模式匹配、条件拒绝、任意模式三种验证方式
生成资源 不原生支持 generate 规则 Kyverno 可自动生成 ConfigMap、Secret、RBAC 等资源
异常豁免 excludedNamespaces + labelSelector exclude 块 + preconditions Kyverno 支持基于资源上下文的条件豁免
审计模式 --audit-interval + Constraint 状态 background: true + validationFailureAction: Audit Kyverno 审计结果写入 PolicyReport CRD
关键差异： Gatekeeper 的约束实例与模板分离，适合多团队复用同一模板但不同参数；Kyverno 将模板与实例合并为单一 ClusterPolicy，更简洁但参数化需通过变量注入实现。

4.2 策略类型对应表

根据实际生产环境中的常见策略场景，将 Gatekeeper 策略类型映射到 Kyverno 规则类型：

策略场景 Gatekeeper 实现方式 Kyverno 规则类型 迁移难度
禁止特权容器 Rego violation[{"msg": ...}] validate.pattern 低
强制资源限制 Rego violation + input.review.object.spec.containers validate.pattern 或 validate.deny 低
镜像仓库白名单 Rego violation + sprintf 匹配 validate.deny.conditions 中
自动注入 Sidecar Rego mutate + Patch mutate.patchStrategicMerge 中
强制标签 Rego violation + object.metadata.labels validate.pattern 或 validate.deny 低
禁止 HostNetwork Rego violation + input.review.object.spec.hostNetwork validate.pattern 低
命名空间配额生成 不原生支持（需外部控制器） generate 高（新功能）
Pod 安全标准 (PSS) Rego 自定义模板或 k8spsp 库 validate.podSecurity (内置) 低（内置支持）
迁移建议： 对于 Pod 安全标准类策略，优先使用 Kyverno 内置的 validate.podSecurity 规则，无需手动编写 Rego 或 YAML 模式。

4.3 迁移决策树

以下决策树帮助团队快速判断每条 Gatekeeper 策略的迁移路径：

Gatekeeper → Kyverno 迁移决策树 Gatekeeper 策略 策略类型是什么？ 验证 (Validation) 是否可用 pattern 表达？ validate.pattern validate.deny 变更 (Mutation) 使用 mutate 规则 mutate.patchStrategicMerge 生成 (Generation) 使用 generate 规则 generate 规则 + 同步 决策要点 1. 优先检查 Kyverno 是否已有内置规则（如 Pod Security、Dockerfile 检查） 2. 复杂 Rego 逻辑（循环、嵌套条件）拆分为多个 validate.deny 条件 3. 涉及外部数据（Registry、Git）使用 Kyverno 的 API Call 或 Context 变量 4. 审计模式策略设置 validationFailureAction: Audit + background: true 5. 生成类策略需额外配置 generate 同步以避免漂移

4.4 常见迁移陷阱

根据多个生产环境迁移案例，以下陷阱最容易导致策略失效或集群异常：

陷阱 1：Rego 中的 any / all 语义误用
Gatekeeper 中 any(container, ...) 表示“至少一个容器满足条件”，而 Kyverno 的 anyPattern 表示“任意一个模式匹配即通过”。迁移时需反转逻辑：将 Rego 的否定条件转换为 Kyverno 的 deny.conditions。
陷阱 2：忽略 preconditions 导致空指针异常
Kyverno 在 validate.deny 中访问嵌套字段（如 spec.containers[].securityContext）时，如果 Pod 未定义该字段，会直接报错。必须添加 preconditions 检查字段存在性。
正确做法示例： 
preconditions:
  all:
  - key: "{{ request.object.spec.containers[] }}"
    operator: NotEquals
    value: ""
validate:
  deny:
    conditions:
      any:
      - key: "{{ request.object.spec.containers[].securityContext.privileged }}"
        operator: Equals
        value: true
陷阱 3：Gatekeeper 的 input.review 与 Kyverno 的 request 变量差异
Gatekeeper 使用 input.review.object 访问资源，Kyverno 使用 request.object。此外，Kyverno 的 request.operation 返回小写字符串（如 create），而 Gatekeeper 返回大写（如 CREATE）。
陷阱 4：变更规则顺序与冲突
Kyverno 按 spec.rules 顺序执行 mutate，后执行的规则可能覆盖先执行的变更。迁移时需将 Gatekeeper 的多个 mutate 操作合并为单个 patchStrategicMerge 或使用 patchesJson6902 精确控制顺序。
陷阱 5：审计模式下的资源状态不一致
设置 validationFailureAction: Audit 后，Kyverno 仅标记违规但不拒绝。如果 Gatekeeper 原策略是强制拒绝（enforcementAction: deny），迁移初期建议先设为 Audit 观察一周，确认无误后再切换为 Enforce。

4.5 迁移适配检查清单

以下清单用于每条策略迁移后的核验：

检查项 验证方法 通过标准
语法正确性 kubectl apply -f policy.yaml 无报错，策略状态为 Ready
匹配范围一致 创建测试资源，检查是否被策略命中 与 Gatekeeper 原策略命中结果一致
拒绝/变更行为 创建违规资源，观察是否被拒绝或变更 拒绝消息或变更内容与原策略一致
异常豁免生效 创建带豁免标签/注解的资源 策略跳过该资源
审计报告生成 检查 PolicyReport 或 ClusterPolicyReport 违规资源被正确记录
性能影响 监控 APIServer 延迟和 Kyverno 内存 P99 延迟增加 < 50ms，内存 < 500Mi
← 上一章 📖 返回目录 下一章 →