📚 课程目录第3章 Kyverno策略结构

3. Kyverno 策略结构：YAML策略文件结构详解、策略作用域与规则类型

Kyverno 策略以标准的 Kubernetes YAML 清单形式定义，遵循 Kubernetes 资源模型。理解其核心结构、作用域（ClusterPolicy vs Policy）以及规则类型（Mutate/Validate/Generate）是编写可靠策略的基础。本章将逐一拆解这些概念，并通过图示和表格帮助建立清晰的认知。

3.1 YAML 策略文件结构详解

一个完整的 Kyverno 策略 YAML 文件由四个顶层字段构成：apiVersion、kind、metadata 和 spec。其中 spec 是策略的核心，包含一个或多个 rules 数组。

核心结构模板：

apiVersion: kyverno.io/v1
kind: ClusterPolicy   # 或 Policy
metadata:
  name: <策略名称>
  annotations:
    policies.kyverno.io/title: <标题>
    policies.kyverno.io/description: <描述>
spec:
  rules:
  - name: <规则名称>
    match:
      resources:
        kinds:
        - <资源类型>
    # 规则具体内容（mutate / validate / generate）

字段	说明	是否必填
`apiVersion`	固定为 `kyverno.io/v1`	是
`kind`	`ClusterPolicy`（集群范围）或 `Policy`（命名空间范围）	是
`metadata.name`	策略名称，必须符合 DNS-1123 子域名规范	是
`spec.rules`	规则数组，至少包含一条规则	是
`spec.rules[].name`	规则名称，在同一策略内唯一	是
`spec.rules[].match`	定义规则匹配的资源条件（kinds、namespaces、selector 等）	是
`spec.rules[].exclude`	定义排除条件，优先级高于 match	否
`spec.rules[].context`	引入外部数据（ConfigMap、API 调用、变量等）	否
`spec.rules[].preconditions`	条件表达式，满足后才执行规则主体	否

最佳实践： 始终为策略添加 policies.kyverno.io/title 和 policies.kyverno.io/description 注解。这些注解会在 kyverno policies 命令输出中显示，便于团队理解和审计。

3.2 策略作用域：ClusterPolicy vs Policy

Kyverno 提供两种策略作用域，选择哪种取决于策略需要生效的范围：

ClusterPolicy：集群级资源，不绑定到特定命名空间。可以匹配所有命名空间中的资源，也可以匹配集群范围的资源（如 Node、PersistentVolume、ClusterRole）。
Policy：命名空间级资源，只能在其所属命名空间内生效。匹配的资源必须位于该命名空间中。

常见误区： 使用 Policy 时，如果 match 中指定了集群范围的资源（如 Node），策略将不会生效。集群范围资源只能由 ClusterPolicy 处理。

对比维度	ClusterPolicy	Policy
作用范围	整个集群	单个命名空间
匹配集群资源	支持（Node、PV、ClusterRole 等）	不支持
匹配命名空间资源	支持（可通过 `match.resources.namespaces` 过滤）	仅限自身命名空间
典型使用场景	全局安全基线、集群级准入控制、跨命名空间策略	租户隔离、特定团队的自定义规则
RBAC 要求	需要集群管理员权限	命名空间管理员即可

3.3 规则类型：Mutate / Validate / Generate

每条规则必须指定一种操作类型。Kyverno 支持三种核心规则类型，分别对应不同的策略目标：

规则类型	关键字	触发时机	行为	典型场景
Mutate	`mutate`	资源创建/更新时（准入阶段）	修改传入的资源配置，再提交给 API Server	自动注入 Sidecar、添加标签/注解、设置默认资源限制
Validate	`validate`	资源创建/更新时（准入阶段）	检查资源配置是否符合规则，不符合则拒绝或生成告警	强制安全上下文、禁止特权容器、检查镜像来源
Generate	`generate`	资源创建时（准入阶段）或按需同步	根据规则自动创建新的关联资源	自动创建 NetworkPolicy、自动创建命名空间配额、自动创建 Secret

  规则类型选择指南：
  需要自动修正用户提交的资源 → 使用 mutate
需要强制合规，不符合就拒绝 → 使用 validate（配合 deny 动作）
需要自动创建配套资源 → 使用 generate

3.4 规则类型详解与示例

3.4.1 Mutate 规则

Mutate 规则在资源被 API Server 持久化之前修改其内容。Kyverno 支持两种修改方式：patchesJson6902（JSON Patch 标准）和 overlay（声明式覆盖）。

# 示例：自动为所有 Pod 添加标签 "team: platform"
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: add-team-label
spec:
  rules:
  - name: add-platform-label
    match:
      resources:
        kinds:
        - Pod
    mutate:
      overlay:
        metadata:
          labels:
            team: platform

3.4.2 Validate 规则

Validate 规则检查资源是否符合预期。通过 deny 动作可以拒绝不合规资源；通过 pattern 或 anyPattern 可以定义允许的模式。

# 示例：禁止使用 latest 镜像标签
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-latest-tag
spec:
  rules:
  - name: require-image-tag
    match:
      resources:
        kinds:
        - Pod
    validate:
      message: "使用 'latest' 镜像标签是不允许的"
      pattern:
        spec:
          containers:
          - image: "!*:latest"

3.4.3 Generate 规则

Generate 规则在检测到匹配的资源创建时，自动生成另一个资源。生成的资源会与源资源建立“所有者引用”关系，源资源删除时生成的资源也会被自动清理。

# 示例：为每个新 Namespace 自动创建默认 NetworkPolicy
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: generate-default-networkpolicy
spec:
  rules:
  - name: generate-networkpolicy
    match:
      resources:
        kinds:
        - Namespace
    generate:
      kind: NetworkPolicy
      name: default-deny-all
      namespace: "{{request.object.metadata.name}}"
      synchronize: true
      data:
        spec:
          podSelector: {}
          policyTypes:
          - Ingress
          - Egress

Generate 规则关键参数：

synchronize: true — 当生成的资源被手动修改后，Kyverno 会自动将其恢复为规则定义的原始状态。
clone — 可以从已有的源资源克隆生成，而不是使用 data 字段定义。

3.5 规则执行顺序与优先级

当多个策略或规则匹配同一个资源时，执行顺序遵循以下规则：

Mutate 规则先于 Validate 规则执行：确保资源在被验证前已经过修正。
Generate 规则在 Mutate 和 Validate 之后执行：生成的资源不会影响当前资源的准入决策。
同类型规则按背景检查（background）和准入（admission）区分：准入规则优先于背景扫描规则。
同类型、同优先级的规则按策略名称字母序执行：因此建议为策略命名时使用有意义的、可排序的前缀。

注意： 如果多个 Mutate 规则修改同一个字段，后执行的规则会覆盖先执行的规则。建议通过 preconditions 或 exclude 避免规则冲突。

3.6 本章小结

Kyverno 策略 YAML 由 apiVersion、kind、metadata 和 spec.rules 构成，rules 是核心。
ClusterPolicy 作用于整个集群，Policy 作用于单个命名空间；集群资源只能由 ClusterPolicy 处理。
三种规则类型：Mutate（修改）、Validate（检查/拒绝）、Generate（自动创建）。
规则执行顺序：Mutate → Validate → Generate，同类型按名称字母序。