📚 课程目录第4章回滚场景分析

4. 策略语言入门：Kyverno策略YAML结构、match/exclude规则、validate/mutate/generate动作类型

Kyverno 的策略语言完全基于 Kubernetes 原生的 YAML 声明式语法，这意味着任何熟悉 Kubernetes 资源的工程师都能快速上手。一个完整的 Kyverno 策略由三个核心层次构成：顶层结构、匹配/排除规则 以及 动作类型。本章将逐一拆解这些要素，帮助你建立对策略语言的系统认知。

4.1 策略YAML顶层结构

每个 Kyverno 策略都是一个标准的 Kubernetes 自定义资源（CRD），其 API 组为 kyverno.io/v1，资源类型为 ClusterPolicy（集群范围）或 Policy（命名空间范围）。以下是一个最小化的策略骨架：

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-labels
spec:
  validationFailureAction: Audit   # 或 Enforce
  rules:
  - name: check-required-labels
    match:
      resources:
        kinds:
        - Pod
    validate:
      message: "标签 'app.kubernetes.io/name' 是必需的"
      pattern:
        metadata:
          labels:
            app.kubernetes.io/name: "?*"

关键字段说明：

字段路径	类型	说明
`spec.validationFailureAction`	string	策略违规时的行为：`Audit`（仅记录告警，不拦截）或 `Enforce`（强制拦截）
`spec.background`	boolean	是否对已有资源进行后台扫描（默认 `true`）
`spec.rules[]`	array	规则列表，每个规则包含 match、exclude、动作块
`spec.rules[].name`	string	规则名称，在同一策略内必须唯一

最佳实践： 在开发阶段始终使用 validationFailureAction: Audit，配合 kyverno scan 命令验证策略效果，确认无误后再切换为 Enforce。

4.2 match与exclude规则：精准控制策略作用域

每个规则都必须包含 match 声明，用于定义策略应该应用于哪些资源。exclude 则是可选的，用于从匹配结果中排除特定资源。两者共享相同的匹配语法，支持按资源类型、标签选择器、命名空间、名称模式、注解等多种维度进行筛选。

4.2.1 match规则示例

match:
  resources:
    kinds:
    - Deployment
    - StatefulSet
    namespaces:
    - production
    - staging
    selector:
      matchLabels:
        app: frontend
    annotations:
      security.kyverno.io/scan: "required"

4.2.2 exclude规则示例

exclude:
  resources:
    kinds:
    - Namespace
    names:
    - kube-system
    - kyverno-*
    namespaceSelector:
      matchExpressions:
      - key: kubernetes.io/metadata.name
        operator: NotIn
        values:
        - kube-system

  匹配逻辑优先级： Kyverno 先执行 match 筛选出候选资源，再应用 exclude 从中移除不需要的资源。如果 match 未命中任何资源，则 exclude 不会生效。

下表总结了常用的匹配/排除维度：

维度	字段	匹配方式
资源类型	`kinds`	精确匹配 API 版本+Kind，如 `v1/Pod`、`apps/v1/Deployment`
命名空间	`namespaces`	精确匹配命名空间名称列表
标签选择器	`selector`	支持 `matchLabels` 和 `matchExpressions`
名称模式	`names`	支持通配符 `*` 和 `?`
注解	`annotations`	键值对精确匹配
命名空间选择器	`namespaceSelector`	基于命名空间标签的表达式匹配

4.3 三大动作类型：validate / mutate / generate

Kyverno 提供三种核心动作类型，分别对应策略的不同职责：校验（validate）、变更（mutate） 和 生成（generate）。一个规则只能包含其中一种动作。

4.3.1 validate：校验与拦截

validate 用于检查资源是否符合预期规范，是策略即代码中最常用的动作。它支持多种校验模式：

pattern：声明式模式匹配，使用 ?*（非空）、*（可选）、""（空值）等通配符
anyPattern：多个 pattern 中满足任意一个即通过
deny：基于 CEL（Common Expression Language）或原始条件表达式定义拒绝规则
podSecurity：内置的 Pod 安全标准检查

validate:
  message: "容器镜像必须来自内部仓库 registry.internal.io"
  pattern:
    spec:
      containers:
      - image: "registry.internal.io/*"

4.3.2 mutate：自动变更资源

mutate 允许在资源创建或更新时自动修改其字段，无需人工干预。常见的场景包括：自动注入 Sidecar 容器、添加标签/注解、修改安全上下文等。

mutate:
  patchesJson6902: |-
    - op: add
      path: "/metadata/labels/team"
      value: "platform"
  targets:
  - kind: Pod

mutate 支持两种变更策略：

策略类型	语法	适用场景
overlay	声明式覆盖，类似 Kustomize 的 patchesStrategicMerge	添加/替换简单字段
patchesJson6902	JSON Patch 标准（RFC 6902）	复杂的增删改操作

4.3.3 generate：自动创建关联资源

generate 用于在匹配资源创建时，自动生成另一个关联资源。典型场景包括：为每个 Namespace 自动创建 NetworkPolicy、ResourceQuota、LimitRange 等。

generate:
  kind: NetworkPolicy
  name: default-deny
  namespace: "{{request.object.metadata.name}}"
  synchronize: true
  data:
    spec:
      podSelector: {}
      policyTypes:
      - Ingress
      - Egress

注意： generate 动作默认只在资源创建时触发一次。如果设置 synchronize: true，Kyverno 会持续同步生成资源，确保其与策略定义保持一致，即使被手动修改也会被覆盖。

4.4 策略执行流程总览

下图展示了 Kyverno 策略引擎处理一个资源请求时的完整流程：

4.5 动作类型对比与选择

在实际项目中，合理选择动作类型直接影响策略的可维护性和执行效率。下表从多个维度对比三种动作：

维度	validate	mutate	generate
核心职责	检查并拦截不合规资源	自动修改资源字段	创建关联的辅助资源
执行时机	创建/更新时	创建/更新时	创建时（可同步）
对资源的影响	只读，不修改	直接修改请求内容	创建新资源
失败行为	Audit 记录 / Enforce 拒绝	变更失败则拒绝请求	生成失败记录事件
典型场景	强制标签、禁止特权容器、镜像来源校验	注入 Sidecar、添加默认标签、设置资源限制	自动创建 NetworkPolicy、ResourceQuota、RoleBinding

  组合使用技巧： 在同一个策略中可以定义多个规则，每个规则选择不同的动作。例如：规则1使用 validate 检查是否包含必需标签，规则2使用 mutate 自动补全缺失的标签。Kyverno 会按规则定义的顺序依次执行。

4.6 策略语言核心概念关系图

下图展示了策略语言中各核心概念之间的逻辑关系：

4.7 本章小结

通过本章的学习，你已经掌握了 Kyverno 策略语言的三大核心要素：

YAML 结构：基于 Kubernetes CRD 的声明式语法，顶层包含 spec.rules 数组
match/exclude 规则：通过资源类型、标签、命名空间等多维度精准控制策略作用域
三种动作类型：validate（校验拦截）、mutate（自动变更）、generate（自动生成），每种动作对应不同的策略职责