Velero 恢复参考指南跨命名空间恢复与 PV/PVC 存储类映射【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文基于 Velero 仓库中的 restore-reference.md 展开系统讲解在 Kubernetes 恢复场景下最常用的两项定制能力将备份中的资源恢复到与原命名空间不同的目标命名空间以及在恢复过程中改写 PV/PVC及 StatefulSet 卷模板的存储类。读完本文你将掌握--namespace-mappings标志的用法与底层实现以及如何通过 ConfigMap 驱动内置的change-storage-class恢复项动作插件从而在恢复时完成存储类迁移适配跨集群、跨环境如开发环境到生产环境的备份恢复与迁移需求。一、背景为什么恢复时需要“改写”Velero 的恢复流程默认把备份中的资源原样还原原资源在哪个命名空间就恢复到哪个命名空间PV/PVC 引用了哪个存储类就继续使用哪个存储类。但在真实的生产迁移中这两种“原样还原”往往不满足需求跨命名空间迁移例如把备份从old-ns-1恢复到new-ns-1用于环境隔离、多租户拆分或应用重构存储类变更例如源集群使用standard存储类目标集群使用fast或从自建存储迁移到云厂商存储如 AWS EBS、Azure Disk存储类名称通常不一致。针对这两种需求Velero 分别在恢复请求Restore规格和**恢复项动作插件Restore Item Action Plugin**两个层面提供了内建支持下面分别展开。二、跨命名空间恢复--namespace-mappings标志2.1 命令用法原文档给出了最直接的用法在创建恢复时通过--namespace-mappings指定“源命名空间:目标命名空间”的映射多个映射用英文逗号分隔velero restore create RESTORE_NAME \ --from-backup BACKUP_NAME \ --namespace-mappings old-ns-1:new-ns-1,old-ns-2:new-ns-2即old-ns-1中的资源被恢复到new-ns-1old-ns-2中的资源被恢复到new-ns-2未出现在映射中的命名空间其资源仍恢复到原命名空间。2.2 CLI 解析与规格落地从源码看该标志在 CLI 层被定义为一个“键值对 Map”类型的参数。在 pkg/cmd/cli/restore/create.go 中NamespaceMappings: flag.NewMap().WithEntryDelimiter(,).WithKeyValueDelimiter(:),其含义是多个映射条目用,分隔每个条目内部用:分隔键源命名空间与值目标命名空间。该选项的帮助文本为Namespace mappings from name in the backup to desired restored name in the form src1:dst1,src2:dst2,...在创建 Restore 自定义资源时CLI 将解析后的 Map 直接写入RestoreSpec.NamespaceMapping字段见 pkg/cmd/cli/restore/create.go。该字段在 API 类型中的定义位于 pkg/apis/velero/v1/restore_types.go// NamespaceMapping is a map of source namespace names // to target namespace names to restore into. Any source // namespaces not included in the map will be restored to // namespaces of the same name. NamespaceMapping map[string]string json:namespaceMapping,omitempty也就是说映射关系最终以spec.namespaceMapping的形式持久化在 Restore 对象中未映射的命名空间保持原名恢复。CLI 侧的解析行为也有对应测试覆盖见 pkg/cmd/cli/restore/create_test.go测试传入--namespace-mappings a:b并断言o.NamespaceMappings.String()的解析结果一致。2.3 底层实现命名空间映射如何生效映射在服务端由恢复控制器读取并贯穿整个恢复流程核心实现位于 pkg/restore/restore.go。资源目标命名空间的计算在getSelectedRestoreableItems中每个备份项的目标命名空间按如下逻辑计算pkg/restore/restore.gotargetNamespace : originalNamespace if target, ok : ctx.restore.Spec.NamespaceMapping[originalNamespace]; ok { targetNamespace target }命名空间资源自身的映射对于namespaces这类集群级资源映射同样生效——当源命名空间在映射表中时恢复出的 Namespace 对象使用目标名pkg/restore/restore.go。连带引用关系的处理映射不仅作用于资源本身还会顺带修正依赖关系包括备份项引用的其他命名空间如跨命名空间引用会按同一映射改写pkg/restore/restore.goPV 的ClaimRef.Namespace会依据映射改写确保 PV 与 PVC 在目标命名空间中仍能正确绑定pkg/restore/restore.go角色绑定RoleBinding中subject.namespace会被改写见 pkg/restore/actions/rolebinding_action.go 与 pkg/restore/actions/clusterrolebinding_action.go。因此使用--namespace-mappings不只是简单地把每个对象换个命名空间创建而是会联动修正 Namespace、PV 绑定、RBAC 引用等关联关系保证恢复出的应用是自洽的。三、恢复时改写 PV/PVC 存储类3.1 工作原理内置 RestoreItemAction 插件存储类改写由 Velero 内置的change-storage-class恢复项动作插件完成源码位于 pkg/restore/actions/change_storageclass_action.go。该插件通过AppliesTo声明其作用对象pkg/restore/actions/change_storageclass_action.goIncludedResources: []string{persistentvolumeclaims, persistentvolumes, statefulsets},即它会在恢复过程中处理三类资源PVC、PV、StatefulSet后者用于改写volumeClaimTemplates中的存储类。插件在服务端启动时被注册为内置插件见 pkg/cmd/server/plugin/plugin.go 中对change-storage-class的注册逻辑。插件的执行逻辑Execute为通过标签velero.io/change-storage-class: RestoreItemAction读取插件专属 ConfigMap若 ConfigMap 不存在或data为空则原样返回对象不做任何修改对 PV/PVC读取spec.storageClassName在 ConfigMap 的data中查找映射若找到映射还校验目标存储类在集群中真实存在通过 StorageClass API 查询见 pkg/restore/actions/change_storageclass_action.go随后把spec.storageClassName改写为映射后的值对 StatefulSet遍历spec.volumeClaimTemplates并逐个改写其中的存储类pkg/restore/actions/change_storageclass_action.go。上述流程均有单元测试覆盖见 pkg/restore/actions/change_storageclass_action_test.go其中TestChangeStorageClassActionExecute覆盖了 PV、PVC、StatefulSet 的各类映射与缺失场景。3.2 配置 ConfigMap原文档给出了完整的配置示例。创建 ConfigMap 于 Velero 所在命名空间通常为velero并打上两组必须的标签apiVersion: v1 kind: ConfigMap metadata: # any name can be used; Velero uses the labels (below) # to identify it rather than the name name: change-storage-class-config # must be in the velero namespace namespace: velero # the below labels should be used verbatim in your # ConfigMap. labels: # this value-less label identifies the ConfigMap as # config for a plugin (i.e. the built-in change storage # class restore item action plugin) velero.io/plugin-config: # this label identifies the name and kind of plugin # that this ConfigMap is for. velero.io/change-storage-class: RestoreItemAction data: # add 1 key-value pairs here, where the key is the old # storage class name and the value is the new storage # class name. old-storage-class: new-storage-class需要特别说明的几点标签是关键Velero 不依赖 ConfigMap 的名称而是通过标签识别其归属插件。velero.io/plugin-config: 表明这是一个插件配置velero.io/change-storage-class: RestoreItemAction表明这是change-storage-class恢复项动作插件的配置命名空间必须是 Velero 所在命名空间否则插件无法读取data中每一对键值都是一个映射键为旧的存储类名值为新的存储类名可同时配置多组。一个真实可用的示例假设要把standard映射为gp2AWS EBSapiVersion: v1 kind: ConfigMap metadata: name: change-storage-class-config namespace: velero labels: velero.io/plugin-config: velero.io/change-storage-class: RestoreItemAction data: standard: gp2配置完成后只需正常发起恢复无需额外标志插件便会在恢复过程中自动改写匹配的 PV/PVC 存储类velero restore create restore-1 --from-backup backup-13.3 注意事项目标存储类必须存在插件在改写前会校验目标存储类已在集群中创建若目标存储类不存在恢复会报错见 pkg/restore/actions/change_storageclass_action.go因此请先确认目标存储类已就绪无匹配时不报错若资源未指定存储类或存储类不在映射表中插件会跳过并原样保留StatefulSet 支持不仅独立 PV/PVC 会被改写StatefulSet 的volumeClaimTemplates也会一并处理这在恢复有状态工作负载时非常关键。四、两种机制的配合使用跨命名空间恢复与存储类改写是正交的两项能力可同时使用。典型场景将应用从旧集群的legacy命名空间迁移到新集群的production命名空间同时把存储类从standard换成ssdvelero restore create migrate-2026 \ --from-backup legacy-app-backup \ --namespace-mappings legacy:production配合上文中的存储类映射 ConfigMap一次恢复即可同时完成命名空间迁移与存储类切换。五、验证与排查查看恢复结果恢复完成后用velero restore describe RESTORE_NAME与velero restore logs RESTORE_NAME查看详细状态与日志该提示信息同样来自 pkg/cmd/cli/restore/create.go 的 CLI 输出确认命名空间映射生效检查目标命名空间中的资源是否创建成功重点核对 PV 的ClaimRef与 PVC 的绑定关系是否指向目标命名空间确认存储类改写生效kubectl get pvc -n target-ns -o yaml查看 PVC 的spec.storageClassName是否为映射后的目标存储类若改写未发生请检查 ConfigMap 是否位于 Velero 命名空间、标签是否与上文一致、目标存储类是否已存在。六、小结本文完整继承了 restore-reference.md 的核心内容并从源码层面印证了其实现能力配置方式底层实现跨命名空间恢复velero restore create --namespace-mappings old:newRestoreSpec.NamespaceMapping见 pkg/apis/velero/v1/restore_types.go、pkg/restore/restore.go存储类改写Velero 命名空间内的插件配置 ConfigMap内置change-storage-classRestoreItemAction 插件见 pkg/restore/actions/change_storageclass_action.go这两项能力都以“零改造备份数据”的方式在恢复阶段动态完成改写是 Velero 实现跨环境、跨集群备份恢复与迁移的关键武器。相关文档与示例可继续在仓库中查阅restore-reference.md、create.go 及其测试 create_test.go、change_storageclass_action.go 及其测试 change_storageclass_action_test.go。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Velero 恢复参考指南跨命名空间恢复与 PV/PVC 存储类映射【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文基于 Velero 仓库中的 restore-reference.md 展开系统讲解在 Kubernetes 恢复场景下最常用的两项定制能力将备份中的资源恢复到与原命名空间不同的目标命名空间以及在恢复过程中改写 PV/PVC及 StatefulSet 卷模板的存储类。读完本文你将掌握--namespace-mappings标志的用法与底层实现以及如何通过 ConfigMap 驱动内置的change-storage-class恢复项动作插件从而在恢复时完成存储类迁移适配跨集群、跨环境如开发环境到生产环境的备份恢复与迁移需求。一、背景为什么恢复时需要“改写”Velero 的恢复流程默认把备份中的资源原样还原原资源在哪个命名空间就恢复到哪个命名空间PV/PVC 引用了哪个存储类就继续使用哪个存储类。但在真实的生产迁移中这两种“原样还原”往往不满足需求跨命名空间迁移例如把备份从old-ns-1恢复到new-ns-1用于环境隔离、多租户拆分或应用重构存储类变更例如源集群使用standard存储类目标集群使用fast或从自建存储迁移到云厂商存储如 AWS EBS、Azure Disk存储类名称通常不一致。针对这两种需求Velero 分别在恢复请求Restore规格和**恢复项动作插件Restore Item Action Plugin**两个层面提供了内建支持下面分别展开。二、跨命名空间恢复--namespace-mappings标志2.1 命令用法原文档给出了最直接的用法在创建恢复时通过--namespace-mappings指定“源命名空间:目标命名空间”的映射多个映射用英文逗号分隔velero restore create RESTORE_NAME \ --from-backup BACKUP_NAME \ --namespace-mappings old-ns-1:new-ns-1,old-ns-2:new-ns-2即old-ns-1中的资源被恢复到new-ns-1old-ns-2中的资源被恢复到new-ns-2未出现在映射中的命名空间其资源仍恢复到原命名空间。2.2 CLI 解析与规格落地从源码看该标志在 CLI 层被定义为一个“键值对 Map”类型的参数。在 pkg/cmd/cli/restore/create.go 中NamespaceMappings: flag.NewMap().WithEntryDelimiter(,).WithKeyValueDelimiter(:),其含义是多个映射条目用,分隔每个条目内部用:分隔键源命名空间与值目标命名空间。该选项的帮助文本为Namespace mappings from name in the backup to desired restored name in the form src1:dst1,src2:dst2,...在创建 Restore 自定义资源时CLI 将解析后的 Map 直接写入RestoreSpec.NamespaceMapping字段见 pkg/cmd/cli/restore/create.go。该字段在 API 类型中的定义位于 pkg/apis/velero/v1/restore_types.go// NamespaceMapping is a map of source namespace names // to target namespace names to restore into. Any source // namespaces not included in the map will be restored to // namespaces of the same name. NamespaceMapping map[string]string json:namespaceMapping,omitempty也就是说映射关系最终以spec.namespaceMapping的形式持久化在 Restore 对象中未映射的命名空间保持原名恢复。CLI 侧的解析行为也有对应测试覆盖见 pkg/cmd/cli/restore/create_test.go测试传入--namespace-mappings a:b并断言o.NamespaceMappings.String()的解析结果一致。2.3 底层实现命名空间映射如何生效映射在服务端由恢复控制器读取并贯穿整个恢复流程核心实现位于 pkg/restore/restore.go。资源目标命名空间的计算在getSelectedRestoreableItems中每个备份项的目标命名空间按如下逻辑计算pkg/restore/restore.gotargetNamespace : originalNamespace if target, ok : ctx.restore.Spec.NamespaceMapping[originalNamespace]; ok { targetNamespace target }命名空间资源自身的映射对于namespaces这类集群级资源映射同样生效——当源命名空间在映射表中时恢复出的 Namespace 对象使用目标名pkg/restore/restore.go。连带引用关系的处理映射不仅作用于资源本身还会顺带修正依赖关系包括备份项引用的其他命名空间如跨命名空间引用会按同一映射改写pkg/restore/restore.goPV 的ClaimRef.Namespace会依据映射改写确保 PV 与 PVC 在目标命名空间中仍能正确绑定pkg/restore/restore.go角色绑定RoleBinding中subject.namespace会被改写见 pkg/restore/actions/rolebinding_action.go 与 pkg/restore/actions/clusterrolebinding_action.go。因此使用--namespace-mappings不只是简单地把每个对象换个命名空间创建而是会联动修正 Namespace、PV 绑定、RBAC 引用等关联关系保证恢复出的应用是自洽的。三、恢复时改写 PV/PVC 存储类3.1 工作原理内置 RestoreItemAction 插件存储类改写由 Velero 内置的change-storage-class恢复项动作插件完成源码位于 pkg/restore/actions/change_storageclass_action.go。该插件通过AppliesTo声明其作用对象pkg/restore/actions/change_storageclass_action.goIncludedResources: []string{persistentvolumeclaims, persistentvolumes, statefulsets},即它会在恢复过程中处理三类资源PVC、PV、StatefulSet后者用于改写volumeClaimTemplates中的存储类。插件在服务端启动时被注册为内置插件见 pkg/cmd/server/plugin/plugin.go 中对change-storage-class的注册逻辑。插件的执行逻辑Execute为通过标签velero.io/change-storage-class: RestoreItemAction读取插件专属 ConfigMap若 ConfigMap 不存在或data为空则原样返回对象不做任何修改对 PV/PVC读取spec.storageClassName在 ConfigMap 的data中查找映射若找到映射还校验目标存储类在集群中真实存在通过 StorageClass API 查询见 pkg/restore/actions/change_storageclass_action.go随后把spec.storageClassName改写为映射后的值对 StatefulSet遍历spec.volumeClaimTemplates并逐个改写其中的存储类pkg/restore/actions/change_storageclass_action.go。上述流程均有单元测试覆盖见 pkg/restore/actions/change_storageclass_action_test.go其中TestChangeStorageClassActionExecute覆盖了 PV、PVC、StatefulSet 的各类映射与缺失场景。3.2 配置 ConfigMap原文档给出了完整的配置示例。创建 ConfigMap 于 Velero 所在命名空间通常为velero并打上两组必须的标签apiVersion: v1 kind: ConfigMap metadata: # any name can be used; Velero uses the labels (below) # to identify it rather than the name name: change-storage-class-config # must be in the velero namespace namespace: velero # the below labels should be used verbatim in your # ConfigMap. labels: # this value-less label identifies the ConfigMap as # config for a plugin (i.e. the built-in change storage # class restore item action plugin) velero.io/plugin-config: # this label identifies the name and kind of plugin # that this ConfigMap is for. velero.io/change-storage-class: RestoreItemAction data: # add 1 key-value pairs here, where the key is the old # storage class name and the value is the new storage # class name. old-storage-class: new-storage-class需要特别说明的几点标签是关键Velero 不依赖 ConfigMap 的名称而是通过标签识别其归属插件。velero.io/plugin-config: 表明这是一个插件配置velero.io/change-storage-class: RestoreItemAction表明这是change-storage-class恢复项动作插件的配置命名空间必须是 Velero 所在命名空间否则插件无法读取data中每一对键值都是一个映射键为旧的存储类名值为新的存储类名可同时配置多组。一个真实可用的示例假设要把standard映射为gp2AWS EBSapiVersion: v1 kind: ConfigMap metadata: name: change-storage-class-config namespace: velero labels: velero.io/plugin-config: velero.io/change-storage-class: RestoreItemAction data: standard: gp2配置完成后只需正常发起恢复无需额外标志插件便会在恢复过程中自动改写匹配的 PV/PVC 存储类velero restore create restore-1 --from-backup backup-13.3 注意事项目标存储类必须存在插件在改写前会校验目标存储类已在集群中创建若目标存储类不存在恢复会报错见 pkg/restore/actions/change_storageclass_action.go因此请先确认目标存储类已就绪无匹配时不报错若资源未指定存储类或存储类不在映射表中插件会跳过并原样保留StatefulSet 支持不仅独立 PV/PVC 会被改写StatefulSet 的volumeClaimTemplates也会一并处理这在恢复有状态工作负载时非常关键。四、两种机制的配合使用跨命名空间恢复与存储类改写是正交的两项能力可同时使用。典型场景将应用从旧集群的legacy命名空间迁移到新集群的production命名空间同时把存储类从standard换成ssdvelero restore create migrate-2026 \ --from-backup legacy-app-backup \ --namespace-mappings legacy:production配合上文中的存储类映射 ConfigMap一次恢复即可同时完成命名空间迁移与存储类切换。五、验证与排查查看恢复结果恢复完成后用velero restore describe RESTORE_NAME与velero restore logs RESTORE_NAME查看详细状态与日志该提示信息同样来自 pkg/cmd/cli/restore/create.go 的 CLI 输出确认命名空间映射生效检查目标命名空间中的资源是否创建成功重点核对 PV 的ClaimRef与 PVC 的绑定关系是否指向目标命名空间确认存储类改写生效kubectl get pvc -n target-ns -o yaml查看 PVC 的spec.storageClassName是否为映射后的目标存储类若改写未发生请检查 ConfigMap 是否位于 Velero 命名空间、标签是否与上文一致、目标存储类是否已存在。六、小结本文完整继承了 restore-reference.md 的核心内容并从源码层面印证了其实现能力配置方式底层实现跨命名空间恢复velero restore create --namespace-mappings old:newRestoreSpec.NamespaceMapping见 pkg/apis/velero/v1/restore_types.go、pkg/restore/restore.go存储类改写Velero 命名空间内的插件配置 ConfigMap内置change-storage-classRestoreItemAction 插件见 pkg/restore/actions/change_storageclass_action.go这两项能力都以“零改造备份数据”的方式在恢复阶段动态完成改写是 Velero 实现跨环境、跨集群备份恢复与迁移的关键武器。相关文档与示例可继续在仓库中查阅restore-reference.md、create.go 及其测试 create_test.go、change_storageclass_action.go 及其测试 change_storageclass_action_test.go。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
