Velero 备份排除标签velero.io/exclude-from-backup完全指南原理、用法与源码解析【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文以 Velero 官方备份参考文档v1.1.0 版 backup-reference.md为核心深入讲解如何通过velero.io/exclude-from-backuptrue标签精确排除单个 Kubernetes 资源即使该资源完全匹配备份 Spec 中的资源/命名空间/标签选择器。读完本文你将掌握该标签的完整用法、其与--exclude-resources等过滤参数的差异、底层实现原理、v1.1.0 时代的附加项限制及其后续修复情况并了解如何通过单元测试与 E2E 测试验证排除效果。一、功能定位精确到单个对象的最后一道闸门Velero 的备份过滤体系通常作用在类别层面通过--include-namespaces、--include-resources、--exclude-resources、--include-cluster-resources或资源标签选择器--selector来决定哪些资源进入备份。这些手段要么作用于整个命名空间要么作用于整个资源类型要么作用于一组带特定标签的对象无法精细到某个命名空间里某一个具体对象。velero.io/exclude-from-backup标签正是为弥补这一空白而设计对单个资源对象打上该标签即可把它从备份中排除即使它命中了备份 Spec 定义的所有包含规则。官方文档原话是It is possible to exclude individual items from being backed up, even if they match the resource/namespace/label selectors defined in the backup spec.该标签在 v1.1.0 中随 PR #1588 引入当时的变更记录写得很清楚见 changelogs/CHANGELOG-1.1.mdallows excluding resources from backups with thevelero.io/exclude-from-backuptruelabel典型适用场景包括某个命名空间整体纳入备份但其中某个包含敏感数据的 Secret 或 ConfigMap 需要单独豁免某类资源如 Deployment全量备份但某个特定实例如临时故障排查用的 Pod不需要归档由 BackupItemAction 插件自动注入的附加项additional items中某些对象不希望进入备份归档。二、使用方法一行 kubectl 命令在 v1.1.0 文档site/content/docs/v1.1.0/backup-reference.md中官方给出的用法是kubectl label -n ITEM_NAMESPACE RESOURCE/NAME velero.io/exclude-from-backuptrue各参数含义如下参数说明示例-n ITEM_NAMESPACE资源所在命名空间。仅命名空间作用域的资源需要集群作用域资源如 PV、ClusterRole应省略此参数直接使用RESOURCE/NAME-n myappRESOURCE/NAME资源类型单数或复数形式均可如secret或secrets与对象名称secret/db-password、deployment/nginxvelero.io/exclude-from-backuptrue标签键值对键必须是velero.io/exclude-from-backup值必须是字符串truevelero.io/exclude-from-backuptrue几个可直接套用的实例# 排除命名空间 myapp 中的 secret/db-password kubectl label -n myapp secret/db-password velero.io/exclude-from-backuptrue # 排除集群作用域资源 PersistentVolume pv-production-01无需 -n kubectl label persistentvolume/pv-production-01 velero.io/exclude-from-backuptrue # 撤销排除移除该标签 kubectl label -n myapp secret/db-password velero.io/exclude-from-backup-值匹配是严格的字符串比较需要特别强调的是只有标签值恰好为字符串true时才会触发排除。任何其他值包括false、1、空字符串等都不会生效。这一点在单元测试中有直接覆盖见 pkg/backup/backup_test.go 中的用例resources with velero.io/exclude-from-backup label specified but not true are included——带false、1、标签值的 Pod、Deployment、PV 均被正常备份。这一严格匹配逻辑与源码中的判断语句一一对应详见下文源码实现。三、源码实现标签检查发生在哪个环节3.1 标签常量定义标签键在 Velero API 包中定义为常量pkg/apis/velero/v1/labels_annotations.go// ExcludeFromBackupLabel is the label to exclude k8s resource from backup, // even if the resource contains a matching selector label. ExcludeFromBackupLabel velero.io/exclude-from-backup注释明确点出它的行为特征即使资源命中匹配的选择器标签也会被排除。3.2 实际判断逻辑itemInclusionChecks备份过程中每个对象在被写入归档 tar 之前都要经过包含性检查。核心逻辑位于 pkg/backup/item_backupper.go 的itemInclusionChecks函数func (ib *itemBackupper) itemInclusionChecks(log logrus.FieldLogger, mustInclude bool, metadata metav1.Object, obj runtime.Unstructured, groupResource schema.GroupResource) bool { if mustInclude { log.Infof(Skipping the exclusion checks for this resource) } else { if metadata.GetLabels()[velerov1api.ExcludeFromBackupLabel] true { log.Infof(Excluding item because it has label %strue, velerov1api.ExcludeFromBackupLabel) ib.trackSkippedPV(obj, groupResource, , fmt.Sprintf(item has label %strue, velerov1api.ExcludeFromBackupLabel), log) return false } // NOTE: we have to re-check namespace resource includes/excludes ...从这段代码可以提炼出三个关键事实标签检查位于所有其他过滤检查之前一旦发现velero.io/exclude-from-backup true函数立即返回false后续的命名空间/资源类型包含排除、细粒度名称过滤器namespaceFilter、clusterScopedFilterPolicy等全部短路跳过。这从实现上保证了该标签拥有最高优先级。mustInclude参数会让检查跳过当某个对象被标记为必须包含mustInclude true例如受MustIncludeAdditionalItemAnnotation保护的附加项时标签检查会被旁路。这一点与 v1.1.0 文档中附加项不受该标签约束的说明存在渊源详见第五节。被排除的对象会进入跳过追踪调用trackSkippedPV记录被跳过的对象及其原因便于在备份日志中定位为什么某个对象没进备份。日志输出形如Excluding item because it has label velero.io/exclude-from-backuptrue排查资源莫名缺失时可在 Velero 备份 Pod 日志中检索这一关键字。3.3 优先级为什么标签能战胜一切选择器itemInclusionChecks的执行顺序决定了优先级链条。结合备份主流程 pkg/backup/backup.go 的日志提示一个对象进入归档前经历资源采集Item Collector 按 Spec 过滤→ 每对象包含性检查此处先查排除标签→ 插件附加项展开。因此优先级从高到低大致为velero.io/exclude-from-backuptrue标签最高始终排除Spec 中的命名空间/资源包含排除与细粒度过滤策略备份的标签选择器--selector。在新版细粒度备份过滤设计文档 site/content/docs/main/fine-grained-backup-filters.md 中同样写明Thevelero.io/exclude-from-backuptruelabel always takes precedence over all filters, regardless of whether the item matches global or per-namespace filters.该标签始终优先于所有过滤器无论对象是否匹配全局或按命名空间的过滤器。四、测试证据单元测试如何验证排除行为仓库中的单元测试完整覆盖了该标签的各种组合场景pkg/backup/backup_test.go测试用例场景预期resources with velero.io/exclude-from-backuptrue label are not includedPod、Deployment、PV 三种类型各有一个带标签、一个不带标签带标签的全部不进入备份其余正常归档resources with velero.io/exclude-from-backuptrue label are not included even if matching label selector备份 Spec 设置了--selector ab而带排除标签的对象同时命中ab仍然被排除证明标签优先于选择器resources with velero.io/exclude-from-backup label specified but not true are included标签值分别为false、1、全部正常备份证明仅字符串true生效此外在细粒度过滤功能加入后测试进一步验证了标签与命名空间过滤策略、全局捕获过滤器catch-all、集群作用域过滤策略同时存在时的行为pkg/backup/item_backupper_test.go断言均为带exclude-from-backuptrue的资源即便命中过滤器也必须被排除。在真实集群环境下仓库还提供了 E2E 测试用例test/e2e/resource-filtering/exclude_label.go测试创建带排除标签的 Secret应被排除、带false标签值的 Deployment应被包含和无标签 ConfigMap应被包含执行备份与恢复后校验三者的存在性。你可以直接仿照该用例在自己的集群里做验证velero backup create backup-name --include-namespaces ns --default-volumes-to-fs-backup --wait然后检查备份 tarball 中是否包含/不包含目标对象。五、版本限制v1.1.0 中附加项不被标签约束原文档给出了一个非常重要的版本注意事项site/content/docs/v1.1.0/backup-reference.mdPlease note, in v1.1.0 the label will not be honoured for additional items e.g. PVCs/PVs that are in use by a pod that is being backed up. If this scenario is required, consider upgrading to v1.2.0 or later.即在 v1.1.0 中如果某个 PVC/PV 是被备份 Pod 正在使用的附加项由插件在备份 Pod 时自动带入即使它被打上该标签也不会被排除。需要此能力请升级到 v1.2.0 或更高版本。该限制的修复记录在 changelogs/CHANGELOG-1.2.mdfix excluding additional items with the velero.io/exclude-from-backuptrue label (#1843)从当前仓库源码与测试可以确认现代版本中附加项additional items与关联项related items都遵循该标签附加项场景测试 pkg/backup/backup_test.goadditional items with the velero.io/exclude-from-backup label are not backed up——BackupItemAction 返回pv-1带标签与pv-2无标签最终仅pv-2进入备份归档关联项场景测试 pkg/backup/backup_test.gorelated items with the velero.io/exclude-from-backup label are not backed up——ItemBlockAction 返回同样的两个 PV结果同样是仅无标签的pv-2被备份。因此在规划升级时如果你的备份依赖 PVC/PV 级别的精确排除应确保 Velero 版本不低于 v1.2.0。六、延伸能力给命名空间整体打标签除单个对象外该标签还可以直接打在Namespace对象上效果等价于把该命名空间加入spec.excludedNamespaces。实现位于 pkg/controller/backup_controller.go// Add namespaces with label velero.io/exclude-from-backuptrue into request.Spec.ExcludedNamespaces // Essentially, adding the label velero.io/exclude-from-backuptrue to a namespace would be equivalent to setting spec.ExcludedNamespaces namespaces : corev1api.NamespaceList{} if err : b.kbClient.List(context.Background(), namespaces, kbclient.MatchingLabels{velerov1api.ExcludeFromBackupLabel: true}); err nil { for _, ns : range namespaces.Items { request.Spec.ExcludedNamespaces append(request.Spec.ExcludedNamespaces, ns.Name) } }备份控制器在启动备份流程时会通过标签选择器MatchingLabels{ExcludeFromBackupLabel: true}列举集群中所有带该标签的命名空间并把它们追加到Spec.ExcludedNamespaces。用法# 排除整个命名空间 staging等价于 --exclude-namespaces staging kubectl label namespace/staging velero.io/exclude-from-backuptrue需要注意与对象级排除的一个行为差异命名空间级标签是在控制器层把命名空间写进 Spec 的 ExcludedNamespaces因此它作用于命名空间包含检查这一层而对象级标签作用于itemInclusionChecks的逐对象检查层。两者分别拦截在备份流程的不同阶段但最终效果都是对象不进入归档。七、恢复侧的行为较新版本语义尽管标签名为exclude-from-backup但需要了解的是标签在备份时被打在资源上会随资源清单一起进入备份归档因此较新版本的恢复流程同样会尊重该标签。仓库中的细粒度恢复过滤设计文档 site/content/docs/main/fine-grained-restore-filters.md 对此有明确说明Although named for backup, this label is set on resources at backup time and remains present on items in the archive. The restore pipeline honors it: any item carrying this label is skipped regardless of whether it matches global or per-namespace restore filters.也就是说如果一个资源在备份时或归档中手工修改后带有该标签即使它匹配恢复 Spec 的全局/按命名空间过滤器恢复时也会被跳过。这一恢复侧也生效的语义在规划灾备演练时值得留意——被排除对象不仅不会进备份恢复时也不会被还原。八、最佳实践与注意事项小结值必须精确为true字符串false、1等均不生效打标签时注意不要被 YAML 布尔值写法误导kubectl label命令行的true按字符串处理没有问题。对象级标签与命名空间级标签二选一使用打给具体资源时省略-n则仅适用于集群作用域资源打给 Namespace 对象则排除整个命名空间效果等同spec.excludedNamespaces。确认 Velero 版本若需要在 PVC/PV 等附加项/关联项上使用该标签请确认版本不低于 v1.2.0v1.1.0 中该场景不被支持详见 原文档。排除优于包含但存在旁路mustInclude机制如velero.io/skip-from-backup之外的MustIncludeAdditionalItemAnnotation保护对象会跳过标签检查。如需彻底压制某个插件注入的资源类型更稳妥的做法是结合资源过滤器配置而不是仅依赖对象级标签。排查手段备份日志中的Excluding item because it has label velero.io/exclude-from-backuptrue与trackSkippedPV的跳过记录是确认对象为何未入备份的第一手证据。关联的排除手段除标签外备份 Spec 还支持--exclude-resources按资源类型排除如secrets,rolebindings、--exclude-cluster-scoped-resources、--exclude-namespace-scoped-resources等过滤参数详见 site/content/docs/main/resource-filtering.md。这些是按类型批量排除与标签的逐对象排除互补使用。九、总结velero.io/exclude-from-backuptrue是 Velero 备份过滤体系中粒度最细、优先级最高的一层只需一条kubectl label命令即可精确豁免任意单个资源对象而无需为它单独调整备份 Spec 或拆分配置。其实现上最先检查、命中即短路的设计pkg/backup/item_backupper.go保证了它始终优先于选择器与各类过滤器从 v1.1.0 引入、v1.2.0 补齐附加项支持、再到新版细粒度过滤与恢复侧语义的演进也体现了该机制在 Velero 备份/恢复过滤体系中日益稳固的地位。掌握它你就能在全量备份与精准豁免之间获得最大的灵活性。相关阅读site/content/docs/main/resource-filtering.md备份过滤总览、site/content/docs/main/fine-grained-backup-filters.md细粒度备份过滤设计、site/content/docs/main/fine-grained-restore-filters.md细粒度恢复过滤设计。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考