使用 Velero 实现跨集群迁移：基于对象存储同步的迁移原理与完整实操-开发者社区

使用 Velero 实现跨集群迁移：基于对象存储同步的迁移原理与完整实操

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

本文以 Velero 官方的集群迁移（Cluster Migration）文档为核心，系统讲解如何利用 Velero 的备份/恢复能力，把整个集群的工作负载与数据从一个集群迁移到另一个集群。读完本篇，你将掌握迁移前的兼容性判断要点、两个集群的完整安装与存储位置配置命令、备份/恢复操作流程，并能从源码层面理解支撑迁移的关键机制——对象存储同步（Object Storage Sync）是如何把备份元数据从源集群"搬运"到目标集群的。

一、核心原理：集群迁移建立在对象存储同步之上

Velero 的备份与恢复能力天然适合做集群迁移，而迁移的底层机制正是 Velero 的对象存储同步功能。该机制负责把指定对象存储中的 Velero 资源与集群内的 Backup 自定义资源保持双向一致：

对象存储是事实来源（source of truth）：如果存储桶中存在格式正确的备份文件，但集群里没有对应的 Backup 资源，Velero 会把对象存储中的备份信息同步进 Kubernetes；
反向清理：如果集群里存在Completed的 Backup 对象而对象存储中对应备份 tar 包已不存在，该 Backup 对象会被同步删除；Failed或PartiallyFailed的备份则不会被同步流程清除。

正是这一点让集群迁移场景成立：新集群中原本不存在任何 Backup 对象，但只要目标集群的 Velero 与源集群指向同一个云对象存储位置，目标集群就会自动"看到"源集群写入的备份，从而可以直接发起恢复。

因此，迁移的第一前提非常明确：参与迁移的每个集群上的 Velero 实例，必须配置指向同一个云对象存储位置（相同的 bucket 与 region 等参数）。

对应的实现位于备份同步控制器 backup_sync_controller.go，下文第四节会详细拆解。

二、迁移前必须考虑的四个限制

在开始迁移之前，官方文档列出了四个必须评估的兼容性问题，这些限制直接决定迁移方案是否可行：

跨云厂商的持久卷快照迁移不受原生支持。Velero 无法原生迁移持久卷（PV）快照数据到不同的云厂商。如果需要在云平台之间迁移卷数据，必须启用文件级备份（File System Backup），以文件系统级别备份卷内容。
不支持恢复到更低版本 Kubernetes 的集群。目标集群的 Kubernetes 版本不能低于备份创建时的版本。
跨 Kubernetes 版本迁移需要评估 API 兼容性。在不一致版本的集群之间迁移工作负载可能可行，但迁移前必须考虑各集群间 API 分组的兼容性，尤其是每个自定义资源（CR）的情况。如果 Kubernetes 版本升级破坏了 core/native API 分组的兼容性，在不先更新受影响的自定义资源的前提下，将无法用 Velero 完成迁移。关于 API 分组版本，可参见 EnableAPIGroupVersions 特性。
AWS 与 Azure 插件不支持跨 Region 迁移数据。如果确实需要跨 Region 迁移数据，只能走文件级备份的路径。

三、迁移场景实操：从 Cluster 1 迁移到 Cluster 2

下面的场景演示把资源从 Cluster 1 迁移到 Cluster 2。两个集群使用相同的云厂商（AWS），并都安装 Velero 的 AWS 插件（velero/velero-plugin-for-aws）。

3.1 步骤 1：在 Cluster 1 安装 Velero 并指向对象存储

在 Cluster 1 上确认 Velero 已安装，并通过--bucket标志指向对象存储位置：

velero install --provider aws --image velero/velero:v1.8.0 --plugins velero/velero-plugin-for-aws:v1.4.0 --bucket velero-migration-demo --secret-file xxxx/aws-credentials-cluster1 --backup-location-config region=us-east-2 --snapshot-location-config region=us-east-2

参数要点：

--provider aws：指定云厂商为 AWS；
--bucket velero-migration-demo：备份存储桶。安装时 Velero 会在其中创建一个名为default的 Backup Storage Location（BSL），这就是 Velero 存放备份的位置；
--secret-file xxxx/aws-credentials-cluster1：源集群的 AWS 凭证文件；
--backup-location-config region=us-east-2与--snapshot-location-config region=us-east-2：备份位置与卷快照位置的 Region 配置。注意这两个参数与目标集群必须一致（AWS 插件不支持跨 Region 迁移数据）。

执行velero backup-location get可以查看 Cluster 1 的备份存储位置：

velero backup-location get NAME PROVIDER BUCKET/PREFIX PHASE LAST VALIDATED ACCESS MODE DEFAULT default aws velero-migration-demo Available 2022-05-13 13:41:30 +0800 CST ReadWrite true

3.2 步骤 2：在 Cluster 1 上创建备份

将<BACKUP-NAME>替换为你要使用的备份名：

velero backup create <BACKUP-NAME>

也可以创建定时备份（Scheduled Backup），用 Velero 的schedule操作按既定周期自动备份数据，这是确保数据按你定义的调度自动备份的推荐方式。

关于备份保留期：默认备份保留期以 TTL（time to live）表示，为30 天（720 小时），可用--ttl <DURATION>标志修改。这一点在源码中得到印证：Velero 服务器端配置的默认值定义于 config.go 的defaultBackupTTL = 30 * 24 * time.Hour；--ttl标志的解析逻辑位于 CLI 侧的 backup/create.go（"How long before the backup can be garbage collected"）。备份过期机制的更多说明见 how velero works 中的 "Set a backup to expire" 章节。

3.3 步骤 3：在 Cluster 2 安装 Velero 并指向同一存储位置

在 Cluster 2 上安装 Velero。注意下方安装命令与 Cluster 1 使用了相同的region和--bucket——这是迁移能成立的硬性条件：

velero install --provider aws --image velero/velero:v1.8.0 --plugins velero/velero-plugin-for-aws:v1.4.0 --bucket velero-migration-demo --secret-file xxxx/aws-credentials-cluster2 --backup-location-config region=us-east-2 --snapshot-location-config region=us-east-2

与 Cluster 1 的唯一差别是凭证文件换成了目标集群的aws-credentials-cluster2。

替代方案：先安装、后配置存储位置。你也可以先在 Cluster 2 上安装 Velero，再手动创建指向 Cluster 1 所用--bucket和region的BackupStorageLocations与VolumeSnapshotLocations：

velero backup-location create bsl --provider aws --bucket velero-migration-demo --config region=us-east-2 --access-mode=ReadOnly

velero snapshot-location create vsl --provider aws --config region=us-east-2

两个值得注意的要点：

强烈建议目标集群的 BSL 配置为只读。通过velero backup-location create的--access-mode=ReadOnly标志把 Backup Storage Location 设为只读，可以避免恢复过程中备份被误从对象存储中删除。该标志的可选值（ReadWrite/ReadOnly）与 BSL 类型定义在 backuplocation/create.go。更多可用标志可参考velero backup-location --help；快照位置命令同理可参考velero snapshot-location --help。
--config region=us-east-2中的 region 必须与源集群备份时使用的 region 一致。

3.4 步骤 4：确认 Cluster 1 的备份对象已在 Cluster 2 上可用

继续在 Cluster 2 上操作，确认 Cluster 1 创建的 Velero Backup 对象已经可见（<BACKUP-NAME>与在 Cluster 1 上创建备份时使用的名字相同）：

velero backup describe <BACKUP-NAME>

背后的机制是：Velero 资源与对象存储中的备份文件是同步关系。Cluster 1 的备份所产生的 Velero 资源会通过共享的 Backup Storage Location 同步到 Cluster 2。同步完成后，你就可以在 Cluster 2 上用 Velero 命令访问来自 Cluster 1 的备份了。

默认同步间隔为 1 分钟，因此在 Cluster 2 上检查备份可用性之前可能需要稍等。这个间隔可以通过 Cluster 2 上 Velero 服务器进程的--backup-sync-period标志配置——该标志定义在 pkg/cmd/server/config/config.go，含义为"多久确保对象存储中的所有 Velero 备份在集群中都存在对应的 Backup API 对象"，它是 BSL 未显式指定backupSyncPeriod时的默认值。

3.5 步骤 5：在 Cluster 2 上执行恢复

确认正确的备份可用之后，即可把全部内容恢复到 Cluster 2：

velero restore create --from-backup <BACKUP-NAME>

务必确保<BACKUP-NAME>与 Cluster 1 上的备份名一致。

四、源码级解析：备份同步控制器如何让迁移成立

上面 3.4 步中"Cluster 1 的备份对象会自动出现在 Cluster 2"的行为，由 pkg/controller/backup_sync_controller.go 中的backupSyncReconciler实现。从源码可以看到其关键逻辑：

周期性触发：SetupWithManager中使用kube.NewPeriodicalEnqueueSource以backupSyncReconcilePeriod（1 分钟，定义于 backup_sync_controller.go#L48-L50）为节拍轮询所有 BSL，而不是依赖事件驱动；locationFilterFunc会检查该 BSL 的spec.backupSyncPeriod（若设为0则跳过同步，负数则回退默认值）与status.lastSyncedTime，未到同步时间的位置会被过滤掉。
只同步"已完成"的备份：Reconcile中先调用backupStore.ListBackups()列出对象存储里的备份，再与集群内已有的 Backup 对象做差集（backupsToSync := backupStoreBackups.Difference(clusterBackupsSet)）。随后仅同步状态阶段为Completed、PartiallyFailed或Failed的备份元数据；未完成（如仍在 Finalizing）且未过期的备份会被跳过，防止新集群把"别处正在执行的备份"误当作新请求去执行——这正是从源码结构看迁移场景安全性的关键保护。
适配目标集群的上下文：同步时在 backup_sync_controller.go#L196-L214 处会清空Spec.Hooks（同步来的备份只是执行记录，不应在新集群上执行钩子）、清空ResourceVersion、改写Spec.StorageLocation与对应标签以匹配目标集群的 BSL 名称，并通过filterBackupOwnerReferences校验/清理指向已不存在 Schedule 的 OwnerReference，最后创建 Backup CR。文件系统备份产生的 PodVolumeBackup 资源也会一并同步，并修正其 OwnerReference UID 指向新创建的 Backup。
清理孤儿备份：deleteOrphanedBackups会删除"对象存储中已不存在、但集群里仍是Completed/PartiallyFailed"的备份对象，与文档描述的"对象存储是事实来源"的行为一一对应。

五、验证两个集群

迁移操作完成后，确认 Cluster 2 的行为符合预期：

在 Cluster 2 上运行：
```
velero restore get
```
再运行（用restore get输出中的恢复名替换占位符）：
```
velero restore describe <RESTORE-NAME-FROM-GET-COMMAND>
```

至此，从 Cluster 1 备份的数据应当在 Cluster 2 上可用。

排障提示：如果迁移过程中遇到问题，请先确认 Velero 在两个集群中运行于相同的命名空间（namespace）——备份同步控制器按命名空间列举 Backup 对象，命名空间不一致会导致备份无法正确同步。

六、要点回顾

环节	关键命令/配置	注意事项
源集群安装	`velero install --provider aws --bucket <bucket> --backup-location-config region=<region> ...`	生成名为`default`的 BSL
创建备份	`velero backup create <BACKUP-NAME>`	默认 TTL 30 天（720 小时），可用`--ttl`修改
目标集群存储配置	`velero backup-location create ... --access-mode=ReadOnly`	两个集群必须同 bucket、同 region；建议只读
等待备份可见	`velero backup describe <BACKUP-NAME>`	默认同步间隔 1 分钟，可用服务器端`--backup-sync-period`调整
恢复	`velero restore create --from-backup <BACKUP-NAME>`	备份名须与源集群一致
验证	`velero restore get`/`velero restore describe <name>`	排查时确认两集群 Velero 命名空间一致