Velero 卷备份资源过滤器(Volume Policies)设计解析与实战指南

原创2026-09-15 15:01:221,673 阅读
文章标签:云原生容器编排灾备存储备份恢复CLI运维高可用

Velero 卷备份资源过滤器(Volume Policies)设计解析与实战指南

导读

本文围绕 Velero 的 resource policies(资源过滤器)特性,系统讲解如何通过一份 YAML 策略文件,按容量、存储类、卷类型(NFS/CSI/RBD 等)等条件批量决定卷的备份方式(跳过、文件系统备份或快照),而无需逐个打标签或加注解。读完本文,你将掌握资源策略配置的完整写法、velero backup create --resource-policies-configmap 的使用方式、ConfigMap 引用与生命周期管理,以及该特性在源码中的真实匹配与校验逻辑。

背景:为什么需要一套通用的卷处理策略

在引入本特性之前,Velero 已有大量用于控制资源备份/跳过的过滤器,例如 IncludedNamespaces、ExcludedNamespaces、LabelSelector、OrLabelSelectors,以及 backup.velero.io/backup-volumes、backup.velero.io/backup-volumes-excludes、backup.velero.io/must-include-additional-items 等注解。但对于卷本身,这些手段并不够灵活:

  • 按单个卷逐个使用 opt-in / opt-out 注解,工作量大且易错;
  • 标签选择器要求相关 Pod 上有统一标签,当不同 Pod 标签差异很大时难以批量表达;
  • 用户希望"跳过所有超过某容量的卷""跳过所有 NFS 卷""只备份指定 StorageClass 的卷"这类基于卷自身属性的批量诉求,现有机制无法直接满足。

因此,Velero 引入了资源策略(resource policies):用一套声明式的 YAML 配置,仅依据"卷的条件"(capacity、storageClass、volume source 等)来批量处理卷的备份,同时不需要给 Pod 或卷打任何标签、加任何注解。

目标与边界

Goals:提供灵活的卷策略,且不对 Pod 或卷做任何标签/注解的修改。

Non-Goals(明确不做的事):

  • 仅处理备份场景的卷,不支持 restore;
  • 当前只处理卷,不处理其他资源(但设计上预留了 OtherResourcePolicies 扩展位,见下文源码);
  • 仅支持与运行环境无关、与平台无关的通用卷属性,不支持与特定环境绑定的卷属性。

核心概念与 API 设计

资源策略的 YAML 数据模型由四层结构组成,源码定义位于 internal/resourcepolicies/resource_policies.go,与设计文档中的 API 骨架一一对应:

type VolumeActionType string

// 顶层:策略集合
type ResourcePolicies struct {
    Version        string         `yaml:"version"`
    VolumePolicies []VolumePolicy `yaml:"volumePolicies"`
    // 预留:未来可增加其他资源策略
}

// 单条策略 = 一组条件 + 一个动作
type VolumePolicy struct {
    Conditions map[string]any `yaml:"conditions"`
    Action     Action         `yaml:"action"`
}

// 动作 = 类型 + 可选参数
type Action struct {
    Type       VolumeActionType   `yaml:"type"`
    Parameters map[string]any     `yaml:"parameters,omitempty"`
}

一个典型的策略 YAML 长这样(完整示例见设计文档 handle-backup-of-volumes-by-resources-filters.md):

version: v1
volumePolicies:
# volumePolicies 是列表:若某个卷命中第一条策略,则后续策略不再匹配
# 每条策略由一组条件和一个动作组成
# 一个策略对象中的多个 key 是"与"关系,须全部满足才命中
- conditions:
    # capacity 条件匹配容量落在区间内的卷
    capacity: "0,100Gi"
    csi:
      driver: ebs.csi.aws.com
      fsType: ext4
    storageClass:
    - gp2
    - ebs-sc
  action:
    type: volume-snapshot
    parameters:
      # 可选参数:执行动作时的自定义参数
      volume-snapshot-timeout: "6h"
- conditions:
    capacity: "0,100Gi"
    storageClass:
    - gp2
    - ebs-sc
  action:
    type: file-system-backup
- conditions:
    nfs:
      server: 192.168.200.90
  action:
    type: file-system-backup   # file-system-backup 可以出现多次
- conditions:
    nfs: {}                    # 空值条件:匹配任意 NFS 卷
  action:
    type: skip
- conditions:
    csi:
      driver: aws.efs.csi.driver
  action:
    type: skip

注意:设计文档(面向 v1.11 规划)中动作值写作 file-system-backup 与 volume-snapshot,而在当前仓库的实际实现中,动作枚举值已收敛为 skip、fs-backup、snapshot、custom,详见下文"动作类型"一节,配置时以当前实现为准。

使用流程:从 YAML 模板到 Backup CR 引用

设计文档给出的完整使用路径如下:

  1. 获取 YAML 模板:Velero 提供一个包含所有受支持卷策略的 YAML 模板文件,用户在此基础上模仿编写;
  2. 编写自己的配置:可以从模板中选取部分策略,形成独立配置文件;
  3. 创建 ConfigMap:把配置文件放入 Velero 安装命名空间下的一个 ConfigMap;
  4. 创建备份并引用:执行 velero backup create --resource-policies-configmap $policiesConfigmap 将当前备份与卷策略关联;Velero 会对导入的所有策略做校验,策略不受支持或无法解析时备份直接失败;
  5. Backup CR 记录引用:当前 Backup CR 会记录卷策略 ConfigMap 的引用;
  6. 执行过滤:Velero 先用既有的其他过滤器过滤卷,最后对过滤结果应用卷策略,得出最终需要处理的卷集合。

对应到 CLI 实现,--resource-policies-configmap 标志定义于 pkg/cmd/cli/backup/create.go,并在构建 Backup 时通过 backupBuilder.ResourcePolicies(o.ResPoliciesConfigmap) 写入 BackupSpec(见 create.go)。

实际命令示例:

# 假设已创建好名为 backup01 的策略 ConfigMap
velero backup create my-backup --resource-policies-configmap backup01

Backup CR 中对应的引用字段是 ResourcePolicy(类型为 corev1api.TypedLocalObjectReference),定义于 pkg/apis/velero/v1/backup_types.go:

apiVersion: velero.io/v1
kind: Backup
metadata:
  name: backup-1
spec:
  resourcePolicy:
    kind: ConfigMap
    name: backup01
    apiGroup: ""
  # ... 其余备份规格

动作类型(Action)

Action 决定匹配到的卷以何种方式参与备份(源码常量见 resource_policies.go):

动作值 含义
skip 跳过该卷的备份,无论其本应走文件系统备份还是卷快照
fs-backup 使用文件系统备份方式(Kopia/Restic 上传器)备份该卷
snapshot 对该卷做快照。根据 Velero 配置与备份规格,可对应三种含义:云厂商原生快照、本地 CSI 快照、datamover 数据移动快照
custom 由外部插件处理该卷,Velero 不会对其做快照或文件系统备份

设计上动作值可随备份方式演进继续扩展。skip、fs-backup、snapshot 三种动作可在同一 YAML 中部分或全部配置,且只对相应动作生效。

Action 参数(Parameters):参数是可选的。当前实现中已有两个快照动作专属参数(见 resource_policies.go):

  • dataMover:快照动作选择数据移动器,合法值包括 velero、velero-fs、velero-block(空值与 velero 均表示使用内置默认数据移动器),解析逻辑见 Action.GetDataMover()(resource_policies.go);
  • snapshotClass:CSI 快照时指定 VolumeSnapshotClass 名称,缺省时回退到原有选择逻辑,解析逻辑见 Action.GetSnapshotClass()(resource_policies.go)。

支持的条件(Conditions)

条件的本质是一组卷属性,目标卷需同时满足同一条策略下的全部条件才命中。当前实现可用的条件如下(解析与匹配实现集中在 internal/resourcepolicies/volume_resources.go 与 internal/resourcepolicies/volume_types_conditions.go)。

capacity(容量区间)

capacity: "10Gi,100Gi"   # 匹配容量在 10Gi 到 100Gi(含边界)之间的卷

底层解析逻辑 parseCapacity 把字符串按逗号切分为"下界,上界"两个 resource.Quantity,区间判定 isInRange 实现于 volume_resources.go:

写法 含义
"0,5Gi" 或 "0Gi,5Gi" 容量从 0 到 5Gi,含 0 与 5Gi
",5Gi" 等价于 "0,5Gi"
"5Gi," 容量大于等于 5Gi
"5Gi" 不支持,校验配置时会直接报错

storageClass(存储类)

storageClass:          # 匹配存储类为 gp2 或 ebs-sc 的卷
- gp2
- ebs-sc

匹配实现 storageClassCondition.match 会逐个比对卷的 StorageClassName,命中任意一个即通过(volume_resources.go)。

volume source(卷来源/卷类型)

支持两种写法:

  1. 只写卷来源名称(空对象 {} 表示"匹配任意该来源的卷"),可用的卷来源名称覆盖 Kubernetes 常见类型,源码枚举见 SupportedVolume(volume_types_conditions.go),例如 nfs、rbd、iscsi、csi、hostPath、emptyDir、awsElasticBlockStore、azureDisk、gcePersistentDisk 等:
nfs: {}    # 匹配任意 NFS 卷来源的卷
csi: {}    # 匹配任意 CSI 卷来源的卷
  1. 指定卷来源的详细信息(当前仅支持 CSI driver/volumeAttributes、NFS server/path):
csi:                      # 匹配使用 aws.efs.csi.driver 的 CSI 卷
  driver: aws.efs.csi.driver

nfs:                      # 匹配 server 与 path 均相符的 NFS 卷
  server: 192.168.200.90
  path: /mnt/nfs

卷类型判定函数 getVolumeTypeFromPV / getVolumeTypeFromVolume 分别从 PersistentVolume.Spec 与 Pod 卷的 corev1api.Volume 字段中识别卷来源(volume_types_conditions.go)。

扩展条件:PVC 维度属性

从源码看,条件体系在 v1.11 之后又扩展了若干与 PVC 相关的条件(volume_resources.go),分别是:

  • pvcLabels:要求 PVC 的标签包含给定的 key/value 对(map[string]string),基于 labels.Selector 匹配;
  • pvcPhase:PVC 阶段匹配列表中的任一值(如 Bound、Pending),未绑定(unbound)PVC 也参与策略匹配;
  • pvcVolumeMode:PVC 卷模式,如 Filesystem、Block;
  • pvcAccessModes:PVC 访问模式集合精确相等,如 ReadWriteOnce。

特殊规则定义

设计文档明确了几条必须遵守的规则:

  1. 空值通配:conditions 中某个 key 的值为空对象 {},表示该条件匹配任意值。例如 conditions.nfs: {} 表示只要 PV 使用 NFS 作为 persistentVolumeSource,无论 NFS server 或 path 是什么都命中。源码中 nfsCondition.match 对 Server 与 Path 均为空的情况返回"只要卷有 NFS 源即匹配"(volume_resources.go),csiCondition.match 同理(volume_resources.go)。

  2. 单个过滤值大小限制:每个单独的过滤值应限制在 256 字节以内,防止出现不友好的超长变量赋值。

  3. 容量格式:容量/大小值必须包含下界与上界并用逗号连接,具体四种组合见上文 capacity 表格;不含逗号的单值(如 "5Gi")校验会失败。

  4. 首次命中优先:volumePolicies 是列表,若输入卷命中第一条策略,后续策略将被忽略,以降低多策略并存时的匹配复杂度。源码 Policies.match 按顺序遍历策略列表,返回第一个全部条件都命中的策略动作(resource_policies.go)。

ConfigMap 引用与生命周期

为什么用 ConfigMap 而不是直接写进 BackupSpec

若把资源策略直接塞进 BackupSpec,随着过滤器不断增多,Backup CR 会越来越大、越来越臃肿。因此策略存储在 ConfigMap 中,Backup CR 只保存对 ConfigMap 的引用。ConfigMap 示例:

apiVersion: v1
kind: ConfigMap
metadata:
  name: backup01
  namespace: velero
data:
  policies.yaml: |-
    version: v1
    volumePolicies:
    - conditions:
        capacity: "0,100Gi"
        csi:
          driver: ebs.csi.aws.com
          fsType: ext4
        storageClass:
        - gp2
        - ebs-sc
      action:
        type: volume-snapshot
        parameters:
          volume-snapshot-timeout: "6h"

注意:ConfigMap 的 data 中只能有一个 key(即一份 YAML 数据)。源码 getResourcePoliciesFromConfig 会校验 len(cm.Data) != 1,不满足则报错(resource_policies.go)。ConfigMap 名与 Backup 名无关(并非必须同名),但必须位于 Velero 安装命名空间内。

读取流程 GetResourcePoliciesFromBackup 先从 Backup CR 的 Spec.ResourcePolicy 拿到 ConfigMap 名,再 client.Get 读取并反序列化、校验(resource_policies.go)。

生命周期规则

  • ConfigMap 的生命周期由用户管理,Velero 不负责创建与删除,便于灵活维护;
  • 策略 ConfigMap 会一直保留在集群中,直到用户删除;
  • 与 Backup 不同,策略 ConfigMap 不会同步到新集群;若新集群上没有对应策略,备份将因"resource policies not found"而失败;
  • 同一个策略 ConfigMap 可被多个备份复用;
  • 若备份所引用的 ConfigMap 被删除,不影响已存在的备份;但用该已删除 ConfigMap 创建新备份会失败(resource policies not found)。

全局卷策略(源码扩展)

当前实现还支持通过 Velero 安装参数(--backup-volume-policies-configmap)配置全局卷策略:备份级策略在前、全局策略在后合并,首个命中优先,因此备份级策略可覆盖全局基线(见 GetGlobalResourcePolicies 与 GetResourcePoliciesFromBackupWithGlobal,resource_policies.go)。全局策略仅取 volumePolicies 生效,其余过滤策略会被忽略并记录告警日志。

版本管理与多版本迁移

YAML 数据中引入 version 字段以容纳破坏性变更(不遵循 semver):

  • 向后兼容的增量变更不升版本。例如 v1.12 新增 clusterResourcePolicies 字段时,版本仍保持 v1:
    version: v1
    volumePolicies:
      ....
    clusterResourcePolicies:
      ....
    
  • 破坏性变更必须升版本(如 v1.13 升到 v2):
    version: v2
    # 仅为示例,应尽量规避破坏性变更
    volume-policies:
      ....
    
  • Velero 一次只支持一个版本:使用旧版本 YAML 数据创建的备份将无法被识别。源码 Policies.Validate 会严格比对 version 与当前支持版本,不匹配即报 incompatible version number(resource_policies.go)。

迁移策略:只支持从前一版本迁移到当前版本(控制数据格式转换的复杂度),用户也可以在新版本下直接重新生成 ConfigMap,更便于做版本控制。若存在破坏性变更,需在 Velero 启动前手动为待迁移的 ConfigMap 打上标签,Velero 才会迁移它:

apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    # 该标签可选;若不设置,破坏性变更后备份会失败,需要用户手动更新数据
    velero.io/resource-filter-policies: "true"
  name: example
  namespace: velero
data:
  .....

兼容性与优先级规则

当前 Velero 已有大量资源过滤器,组合使用时要格外小心:

  • IncludedNamespaces / ExcludedNamespaces
  • IncludedResources / ExcludedResources
  • LabelSelector / OrLabelSelectors
  • IncludeClusterResources / UseVolumeSnapshots
  • 注解:velero.io/exclude-from-backup=true、backup.velero.io/backup-volumes-excludes、backup.velero.io/backup-volumes、backup.velero.io/must-include-additional-items

优先级规则:

  1. 卷策略与既有过滤器冲突时,尊重既有过滤器。例如用户在 Pod 上用 opt-out 方式设置了 backup.velero.io/backup-volumes-excludes 注解,同时又用卷策略配置了包含该卷,此时应尊重 opt-out 注解,跳过该卷的备份;
  2. 卷策略之间冲突时,首个命中的策略生效(volumePolicies 顺序即优先级)。

源码视角:策略如何真正作用于备份流程

以 PV 快照路径为例,pkg/backup/item_backupper.go 在决定是否对 PV 做原生快照前,会构造 VolumeFilterData(包含 PV、Pod 卷与 PVC)并调用 GetMatchAction:

vfd := resourcepolicies.NewVolumeFilterData(pv, nil, pvc)
if action, err := ib.backupRequest.ResPolicies.GetMatchAction(vfd); err != nil {
    ...
} else if action != nil && action.Type == resourcepolicies.Skip {
    log.Infof("skip snapshot of pv %s for the matched resource policies", pv.Name)
    ib.backupRequest.SkippedPVTracker.Track(pv.Name, volumeSnapshotApproach,
        "matched action is 'skip' in chosen resource policies")
    return nil
}

即:命中 skip 动作的 PV 会被 SkippedPVTracker 记录并在备份报告中展示跳过原因。对于 PVC 走 CSI / vSphere 插件快照的场景,getMatchAction 会先根据 pvc.Spec.VolumeName 反查 PV,再执行策略匹配;PVC 未绑定时则以 PVC 自身条件(如 pvcPhase、pvcLabels)参与匹配(item_backupper.go)。

整个匹配链路的核心是 structuredVolume:parsePV / parsePodVolume / parsePVC 把 PV、Pod 卷、PVC 的结构化字段归一化为统一形态(容量、存储类、NFS 源、CSI 源、卷类型、PVC 标签/阶段/卷模式/访问模式),随后 Policies.match 依序逐条策略做条件判定(volume_resources.go、resource_policies.go)。

策略的展示与排查

由于策略存于 ConfigMap,仅靠 Backup CR 不易直观阅读,因此 Velero 将策略 ConfigMap 的内容整合进 velero backup describe 的输出,使策略更可读:

velero backup describe my-backup

配合 velero backup logs my-backup 可查看每个卷的匹配与跳过日志(如 skip snapshot of pv ... for the matched resource policies)。若策略解析或校验失败,备份会进入 FailedValidation 状态,日志中会出现类似 fail to read the ResourcePolicies from ConfigMap 或 incompatible version number 的错误信息。

总结

资源策略(volume policies)为 Velero 的卷备份提供了一种声明式、可批量、基于卷自身属性的统一控制方式,是对既有标签/注解过滤机制的有效补充。核心要点:

  • 策略 = 条件组合(与关系)+ 动作(skip / fs-backup / snapshot / custom),命中顺序即优先级;
  • 配置存放于 Velero 命名空间的 ConfigMap,Backup 通过 --resource-policies-configmap 引用,生命周期由用户管理且不同步新集群;
  • version: v1 为当前支持版本,破坏性变更需升版,仅支持从前一版本迁移;
  • 与既有过滤器冲突时尊重既有过滤器;
  • 匹配逻辑、容量解析、动作参数解析与跳过跟踪均有完整源码实现(internal/resourcepolicies),可结合 resource_policies_test.go、volume_resources_test.go 等测试用例进一步验证行为。
登录后查看全文
velero