Velero 卷备份资源过滤器Volume Policies设计解析与实战指南【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文围绕 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.mdversion: 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 backup01Backup CR 中对应的引用字段是ResourcePolicy类型为corev1api.TypedLocalObjectReference定义于 pkg/apis/velero/v1/backup_types.goapiVersion: velero.io/v1 kind: Backup metadata: name: backup-1 spec: resourcePolicy: kind: ConfigMap name: backup01 apiGroup: # ... 其余备份规格动作类型ActionAction决定匹配到的卷以何种方式参与备份源码常量见 resource_policies.go动作值含义skip跳过该卷的备份无论其本应走文件系统备份还是卷快照fs-backup使用文件系统备份方式Kopia/Restic 上传器备份该卷snapshot对该卷做快照。根据 Velero 配置与备份规格可对应三种含义云厂商原生快照、本地 CSI 快照、datamover 数据移动快照custom由外部插件处理该卷Velero 不会对其做快照或文件系统备份设计上动作值可随备份方式演进继续扩展。skip、fs-backup、snapshot三种动作可在同一 YAML 中部分或全部配置且只对相应动作生效。Action 参数Parameters参数是可选的。当前实现中已有两个快照动作专属参数见 resource_policies.godataMover快照动作选择数据移动器合法值包括velero、velero-fs、velero-block空值与velero均表示使用内置默认数据移动器解析逻辑见Action.GetDataMover()resource_policies.gosnapshotClassCSI 快照时指定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,5Gi5Gi,容量大于等于 5Gi5Gi不支持校验配置时会直接报错storageClass存储类storageClass: # 匹配存储类为 gp2 或 ebs-sc 的卷 - gp2 - ebs-sc匹配实现storageClassCondition.match会逐个比对卷的StorageClassName命中任意一个即通过volume_resources.go。volume source卷来源/卷类型支持两种写法只写卷来源名称空对象{}表示匹配任意该来源的卷可用的卷来源名称覆盖 Kubernetes 常见类型源码枚举见SupportedVolumevolume_types_conditions.go例如nfs、rbd、iscsi、csi、hostPath、emptyDir、awsElasticBlockStore、azureDisk、gcePersistentDisk等nfs: {} # 匹配任意 NFS 卷来源的卷 csi: {} # 匹配任意 CSI 卷来源的卷指定卷来源的详细信息当前仅支持 CSI driver/volumeAttributes、NFS server/pathcsi: # 匹配使用 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匹配pvcPhasePVC 阶段匹配列表中的任一值如Bound、Pending未绑定unboundPVC 也参与策略匹配pvcVolumeModePVC 卷模式如Filesystem、BlockpvcAccessModesPVC 访问模式集合精确相等如ReadWriteOnce。特殊规则定义设计文档明确了几条必须遵守的规则空值通配conditions中某个 key 的值为空对象{}表示该条件匹配任意值。例如conditions.nfs: {}表示只要 PV 使用 NFS 作为persistentVolumeSource无论 NFS server 或 path 是什么都命中。源码中nfsCondition.match对Server与Path均为空的情况返回只要卷有 NFS 源即匹配volume_resources.gocsiCondition.match同理volume_resources.go。单个过滤值大小限制每个单独的过滤值应限制在 256 字节以内防止出现不友好的超长变量赋值。容量格式容量/大小值必须包含下界与上界并用逗号连接具体四种组合见上文 capacity 表格不含逗号的单值如5Gi校验会失败。首次命中优先volumePolicies是列表若输入卷命中第一条策略后续策略将被忽略以降低多策略并存时的匹配复杂度。源码Policies.match按顺序遍历策略列表返回第一个全部条件都命中的策略动作resource_policies.go。ConfigMap 引用与生命周期为什么用 ConfigMap 而不是直接写进 BackupSpec若把资源策略直接塞进BackupSpec随着过滤器不断增多BackupCR 会越来越大、越来越臃肿。因此策略存储在 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与GetResourcePoliciesFromBackupWithGlobalresource_policies.go。全局策略仅取volumePolicies生效其余过滤策略会被忽略并记录告警日志。版本管理与多版本迁移YAML 数据中引入version字段以容纳破坏性变更不遵循 semver向后兼容的增量变更不升版本。例如 v1.12 新增clusterResourcePolicies字段时版本仍保持v1version: v1 volumePolicies: .... clusterResourcePolicies: ....破坏性变更必须升版本如 v1.13 升到v2version: v2 # 仅为示例应尽量规避破坏性变更 volume-policies: ....Velero 一次只支持一个版本使用旧版本 YAML 数据创建的备份将无法被识别。源码Policies.Validate会严格比对version与当前支持版本不匹配即报incompatible version numberresource_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-backuptrue、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并调用GetMatchActionvfd : 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。整个匹配链路的核心是structuredVolumeparsePV/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 命名空间的 ConfigMapBackup 通过--resource-policies-configmap引用生命周期由用户管理且不同步新集群version: v1为当前支持版本破坏性变更需升版仅支持从前一版本迁移与既有过滤器冲突时尊重既有过滤器匹配逻辑、容量解析、动作参数解析与跳过跟踪均有完整源码实现internal/resourcepolicies可结合 resource_policies_test.go、volume_resources_test.go 等测试用例进一步验证行为。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考