Velero Restore API 的 ExistingResourcePolicy控制已存在 Kubernetes 资源的还原行为【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读当目标集群中已存在与备份中同名的 Kubernetes 资源时Velero 默认会直接跳过还原——即使集群里的版本与备份中的版本不一致。ExistingResourcePolicy是 Velero 为 Restore API 新增的可选字段它让用户能够显式决定备份中的资源是否应覆盖patch集群中已存在的同名资源。本文基于 existing-resource-policy_design.md 设计文档结合当前仓库中的 API 类型定义、CLI 实现与还原执行逻辑完整讲解该策略的设计演进、最终落地形态与实战用法。读完本文你将掌握none与update两种策略的语义差异、如何通过 YAML 或velero create restore命令配置它以及 Velero 在还原阶段如何处理已存在且内容不同的资源。背景Velero 原有的已存在即跳过行为在设计该功能之前Velero 对集群中已存在资源的还原流程以备份中的Service为例如下Velero 尝试还原该Service先从集群中获取同名的Service若该Service已存在则比较集群实例与备份实例两者不相同跳过还原并添加一条还原警告ServiceAccount对象除外两者相同跳过还原并在日志中记录还原被跳过。也就是说无论备份中的资源与集群中的资源是否一致Velero 都一律跳过用户没有任何手段让备份中的版本覆盖集群中的版本。相关需求记录于 Velero 的 issue #4066。这一局限使得 Velero 难以胜任用备份持续同步/刷新目标集群这类场景因此社区提出了为 Restore API 增加ExistingResourcePolicy的增强提案。设计目标与明确排除的范围设计文档对本提案划定了清晰的边界目标为 Restore API 增加ExistingResourcePolicy让用户决定备份资源是否覆盖集群中已存在的资源。非目标本次不实现不改变ServiceAccount对象既有的还原工作流不支持recreate先删除再重建策略该选项仅作为未来扩展方向保留。与提案无关、明确排除的功能对非 Kubernetes 资源的还原策略对PersistentVolume数据的还原策略PV 数据策略由独立的existingVolumeDataPolicy字段负责。典型使用场景场景 A用备份集群持续同步生产集群假设存在一个与生产集群相同的备份集群。经过一段时间的运行生产集群发生了变化——新增了 Deployment、部分 Secret 被更新。为了让备份集群的 Kubernetes 资源PV 数据除外与生产集群保持同步用户可以定期创建新备份再通过 Velero restore 将最新状态还原到备份集群。此时必须允许备份中的资源覆盖备份集群中已存在的旧版本这正是update策略的用武之地。场景 B帮助识别资源增量delta这里delta指的是上一次备份还原出来的资源、但已不在最新备份中的资源。例如集群 A 有 P1、P2、P3 三个资源先创建 Backup1含 P1、P2、P3并还原到集群 B随后集群 A 删除了 P1、更新了 P2再创建 Backup2此时只含 P2 和 P3于是 delta |集群 B − Backup2|即删除 P1、更新 P2。在第二次还原时用户希望借助还原过程来识别这些资源增量从而判断集群 B 与最新备份之间的差异。三种候选设计方案的权衡设计文档提出了三种 API 形态最终实现选择了方案一。方案一在 Restore API 增加existingResourcePolicy字段不改变 Velero 既有行为仅新增一个可选的existingResourcePolicy字段取值如下取值行为none维持现有行为资源在集群中已存在时直接跳过还原update对已存在的资源尝试打补丁patch若补丁成功集群资源被更新为备份版本并打上最新的 backup/restore 标签若补丁失败记录还原警告并退而求其次仅更新资源的 backup/restore 标签标签更新再失败则记录还原错误recreate若资源已存在则先删除再重建本提案的非目标列为未来范围需要强调的是该设计中任何策略都不会删除资源update策略只是通过 patch 更新资源。示例 A——对velero-protection命名空间中的services和deployments执行none策略Kind: Restore … includeNamespaces: velero-protection includeResources: - services - deployments existingResourcePolicy: none示例 B——对gdpr-application命名空间中的secrets和daemonsets执行update策略Kind: Restore … includeNamespaces: gdpr-application includeResources: - secrets - daemonsets existingResourcePolicy: update方案二增加existingResourcePolicyConfig字段按资源类型细粒度配置该方案允许用户为不同的资源类型指定不同的行为形成资源类型 → 行为的映射existingResourcePolicyConfig: - patch: includedResources: [ ]string - recreate: includedResources: [ ]string注意该方案中没有none行为因为不配置即等价于当前/默认的 Velero 还原行为recreate同样被列为未来范围。示例——对inventory-app命名空间中的secrets与daemonsets执行patchKind: Restore … includeNamespaces: inventory-app existingResourcePolicyConfig: patch: includedResources: - secrets - daemonsets方案三方案一与方案二的组合默认策略 按资源覆盖同时新增existingResourceDefaultPolicy与existingResourcePolicyOverrides两个字段前者描述本次还原的默认行为后者可针对特定资源显式覆盖默认策略。示例——默认patch但对secrets覆盖为noneKind: Restore … includeNamespaces: inventory-app existingResourceDefaultPolicy: patch existingResourcePolicyOverrides: none: includedResources: - secrets实现决策最终团队选择实现方案一理由如下更易于实现更易于扩展为未来演进到方案三保留了空间提供了保留 Velero 既有还原工作流的选项。当前仓库中的最终落地实现Restore API 类型定义方案一落地为RestoreSpec中的ExistingResourcePolicy字段类型为ResourcePolicyType定义在 pkg/apis/velero/v1/restore_types.go// ExistingResourcePolicy specifies the restore behavior for the Kubernetes resource to be restored // optional // nullable ExistingResourcePolicy ResourcePolicyType json:existingResourcePolicy,omitempty策略常量定义于同一文件的第 337–343 行附近// ResourcePolicyTypeNone means velero will not overwrite the resource ResourcePolicyTypeNone ResourcePolicyType none // ResourcePolicyTypeUpdate means velero will try to attempt a patch on // the resource to overwrite the in-cluster one ResourcePolicyTypeUpdate ResourcePolicyType updateResourcePolicyType本身是字符串别名类型// ResourcePolicyType helps specify the ExistingResourcePolicy type ResourcePolicyType string需要注意的是设计文档中草案曾使用PolicyType与PolicyTypeUpdate update的命名而当前仓库实际落地的类型名为ResourcePolicyType字符串取值仍为none/update。CRD 中的字段声明该字段同样体现在生成的 CRD 定义中见 config/crd/v1/bases/velero.io_restores.yamlexistingResourcePolicy: description: ExistingResourcePolicy specifies the restore behavior for the Kubernetes resource to be restored nullable: true type: string还原执行逻辑还原时对已存在资源的处理集中在 pkg/restore/restore.go 中。核心分支逻辑如下若existingResourcePolicy存在且为none记录警告could not restore, ... already exists将该项标记为ItemRestoreResultSkipped跳过若存在且为update调用processUpdateResourcePolicy对已存在的资源执行 patch若未设置该字段保留 Velero 原有的行为——跳过还原并记录警告。对未变化资源集群内版本与备份版本相同的处理在 pkg/restore/restore.go当策略为update时先移除旧的 restore 标签再调用updateBackupRestoreLabels仅更新 backup/restore 标签。processUpdateResourcePolicy的具体流程见 pkg/restore/restore.go从集群实例上移除 restore 标签以便应用最新的 backup/restore 名称用generatePatch(fromCluster, obj)生成集群实例与备份实例之间的补丁若补丁为空说明集群内与期望状态一致直接跳过调用resourceClient.Patch打补丁同时包含资源差异与最新标签若 patch 失败记录警告并降级为仅更新 backup/restore 标签updateBackupRestoreLabels标签更新也失败则追加还原错误。此外ServiceAccount分支pkg/restore/restore.go同样考虑了update策略patch 失败时先移除 restore 标签再尝试仅更新标签成功则将该项标记为ItemRestoreResultUpdated。测试验证仓库中的单元测试对两种策略均有覆盖例如 pkg/restore/restore_test.go 中通过 Builder 分别构造ExistingResourcePolicy(update)与ExistingResourcePolicy(none)的 Restore 来验证不同策略下的还原结果。对应 Builder 方法定义于 pkg/builder/restore_builder.go// ExistingResourcePolicy sets the Restores resource policy. func (b *RestoreBuilder) ExistingResourcePolicy(policy string) *RestoreBuilder { b.object.Spec.ExistingResourcePolicy velerov1api.ResourcePolicyType(policy) return b }CLI--existing-resource-policy标志标志定义与校验设计文档规划了 CLI 变更落地位置 pkg/cmd/cli/restore/create.go当前实现中标志定义如下flags.StringVar(o.ExistingResourcePolicy, existing-resource-policy, , Restore Policy to be used during the restore workflow for Kubernetes resources, can be - none or update)并在还原创建前进行取值校验pkg/cmd/cli/restore/create.goif len(o.ExistingResourcePolicy) 0 !restore.IsResourcePolicyValid(o.ExistingResourcePolicy) { return errors.New(existing-resource-policy has invalid value, it accepts only none, update as value) }即传入除none、update之外的值会被直接拒绝。使用示例velero create restore restore_name --existing-resource-policyupdate描述器describer输出velero restore describe也会展示该策略。普通描述器在 pkg/cmd/util/output/restore_describer.go 中仅在策略非空时输出结构化描述器-o json等在 pkg/cmd/util/output/restore_structured_describer.go 中将其写入specInfo[existingResourcePolicy]。实战配置指南方式一通过 Restore YAML 配置直接创建/编辑 Restore 对象并指定策略例如对gdpr-application命名空间中的secrets与daemonsets执行覆盖更新apiVersion: velero.io/v1 kind: Restore metadata: name: my-restore namespace: velero spec: backupName: my-backup includeNamespaces: - gdpr-application includeResources: - secrets - daemonsets existingResourcePolicy: update应用后执行velero restore describe my-restore或带-o json的结构化输出即可确认策略是否生效。方式二通过 CLI 创建velero create restore my-restore \ --from-backup my-backup \ --include-namespaces gdpr-application \ --include-resources secrets,daemonsets \ --existing-resource-policyupdate行为速查集群内资源状态未设置策略默认noneupdate不存在正常创建正常创建正常创建存在且与备份相同跳过日志记录跳过日志记录仅更新 backup/restore 标签存在且与备份不同跳过 警告跳过 警告标记为 Skipped先 patch 资源差异与标签patch 失败则降级仅更新标签并给出警告总结ExistingResourcePolicy在不破坏 Velero 既有已存在即跳过默认行为的前提下为用户提供了显式覆盖已存在资源的入口none保持默认跳过语义update则通过先 patch 资源差异、失败后降级仅更新标签的容错链路尽量将集群资源同步为备份版本。该功能已在 Restore APIexistingResourcePolicy字段、CRDconfig/crd/v1/bases/velero.io_restores.yaml、CLI--existing-resource-policy与还原执行逻辑pkg/restore/restore.go中完整落地可用于备份集群同步、资源增量识别等场景而recreate先删后建与按资源类型细粒度指定策略则被明确列为未来扩展方向。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考