Velero 卷备份资源过滤器(Volume Policies)设计解析与实战指南
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 引用
设计文档给出的完整使用路径如下:
- 获取 YAML 模板:Velero 提供一个包含所有受支持卷策略的 YAML 模板文件,用户在此基础上模仿编写;
- 编写自己的配置:可以从模板中选取部分策略,形成独立配置文件;
- 创建 ConfigMap:把配置文件放入 Velero 安装命名空间下的一个 ConfigMap;
- 创建备份并引用:执行
velero backup create --resource-policies-configmap $policiesConfigmap将当前备份与卷策略关联;Velero 会对导入的所有策略做校验,策略不受支持或无法解析时备份直接失败; - Backup CR 记录引用:当前 Backup CR 会记录卷策略 ConfigMap 的引用;
- 执行过滤: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(卷来源/卷类型)
支持两种写法:
- 只写卷来源名称(空对象
{}表示"匹配任意该来源的卷"),可用的卷来源名称覆盖 Kubernetes 常见类型,源码枚举见SupportedVolume(volume_types_conditions.go),例如nfs、rbd、iscsi、csi、hostPath、emptyDir、awsElasticBlockStore、azureDisk、gcePersistentDisk等:
nfs: {} # 匹配任意 NFS 卷来源的卷
csi: {} # 匹配任意 CSI 卷来源的卷
- 指定卷来源的详细信息(当前仅支持 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。
特殊规则定义
设计文档明确了几条必须遵守的规则:
-
空值通配:
conditions中某个 key 的值为空对象{},表示该条件匹配任意值。例如conditions.nfs: {}表示只要 PV 使用 NFS 作为persistentVolumeSource,无论 NFS server 或 path 是什么都命中。源码中nfsCondition.match对Server与Path均为空的情况返回"只要卷有 NFS 源即匹配"(volume_resources.go),csiCondition.match同理(volume_resources.go)。 -
单个过滤值大小限制:每个单独的过滤值应限制在 256 字节以内,防止出现不友好的超长变量赋值。
-
容量格式:容量/大小值必须包含下界与上界并用逗号连接,具体四种组合见上文 capacity 表格;不含逗号的单值(如
"5Gi")校验会失败。 -
首次命中优先:
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/ExcludedNamespacesIncludedResources/ExcludedResourcesLabelSelector/OrLabelSelectorsIncludeClusterResources/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
优先级规则:
- 卷策略与既有过滤器冲突时,尊重既有过滤器。例如用户在 Pod 上用 opt-out 方式设置了
backup.velero.io/backup-volumes-excludes注解,同时又用卷策略配置了包含该卷,此时应尊重 opt-out 注解,跳过该卷的备份; - 卷策略之间冲突时,首个命中的策略生效(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 等测试用例进一步验证行为。