Velero v0.11 里程碑解析：Heptio Ark 更名、Restic 多线程恢复与 Ark 备份元数据迁移实战

本篇文章以 changelogs/CHANGELOG-0.11.md 为主线，系统梳理 Velero（原 Heptio Ark）在 v0.11.0 / v0.11.1 两个版本中的关键变更：项目正式从 Ark 更名为 Velero、Restic 升级至 0.9.4 带来的多线程恢复、恢复前等待命名空间与持久卷完成删除的健壮性改进，以及面向 v1.0 升级的 velero migrate-backups 备份元数据迁移命令的完整实操流程。读完本文，你将理解 v0.11 在 Velero 演进史上的承上启下作用，并掌握将 Ark 时期遗留备份元数据平滑迁移到新格式、安全升级到 v1.0 的具体方法。

版本概览与发布时间线

CHANGELOG-0.11.md 记录了连续发布的两个小版本，时间与定位如下：

版本	发布日期	定位
v0.11.0	2019-02-28	首个以 Velero 命名的正式版本，完成 Ark 到 Velero 的更名过渡
v0.11.1	2019-05-17	补丁版本，新增 velero migrate-backups 命令，为升级到 v1.0 铺路

v0.11 处于项目早期（v1.0 发布前夜），其核心意义在于：一方面完成了品牌与代码库的更名迁移，另一方面在功能上引入了若干影响后续架构的机制——Restic 多线程恢复、备份压缩包版本文件（backup-version）、ServerStatusRequest 自定义资源等。其中不少机制在当前仓库中仍能找到直接的源码继承，可作为理解这些历史变更的佐证。

重大变更一：Heptio Ark 正式更名为 Velero

更名范围

v0.11.0 是第一个使用新名字 Velero 的发布版本。根据 changelog 的记录（#1184, @nrb），本次更名涉及面非常广：

• 修改了内部 import 路径；
• 修改了环境变量（如 ARK_* 相关的配置变量随之更名）；
• 修改了二进制名称（ark 变为 velero）；
• 修改了容器镜像与 CRD 组相关的命名约定。

对于已经部署 Ark 的用户，官方在 v0.11 发布时提供了专门的迁移指引（参见 changelog 中的 [1] 链接），并强烈建议严格按迁移说明操作，以确保成功升级到 v0.11。这一更名也直接引出了后续 v0.11.1 中 velero migrate-backups 命令存在的意义——历史上以 ark-* 前缀命名的备份元数据文件，需要在升级前转换为新的 velero-* 格式（详见下文）。

更名对备份元数据格式的影响

更名并非只是表面的命名替换。在 Ark 时代，备份的元数据文件以 ark-backup.json 的形式存放于对象存储中；更名后，新的元数据文件变为 velero-backup.json。v0.11 本身对旧格式保持了向后兼容（仍能读取 ark-backup.json），但这为 v1.0 放弃旧格式埋下了伏笔——这也是 v0.11.1 必须提供迁移命令的根本原因。

重大变更二：Restic 升级至 v0.9.4，恢复性能显著提升

变更内容

v0.11.0 将底层文件备份工具 Restic 从旧版本升级到 v0.9.4（#1156, @skriss），并随之调整了调用参数：

• 用 --host 标志替代了旧的 --hostname 标志；
• 判断 Restic 仓库是否已存在的方式，从 restic check 改为 restic stats（#1171, @skriss）——stats 相比 check 开销更低，更适合作为"仓库是否存在"的轻量探测手段。

性能收益

changelog 明确指出，v0.9.4 自带了 multi-threaded restorer（多线程恢复器），使得 restore（恢复）速度显著加快。对于包含大量文件数据的 Pod 卷备份而言，这是恢复侧吞吐量的一次直接提升，也是该版本最容易被用户感知的改进之一。

相关源码佐证

在当前仓库中，Restic 相关的 Pod 卷备份/恢复链路仍然保留了 v0.11 时代的架构脉络，可参考：

• pkg/podvolume/backupper.go 与 pkg/podvolume/restorer.go：定义 Pod 卷级备份/恢复的接口；
• pkg/podvolume/backup_micro_service.go 与 pkg/podvolume/restore_micro_service.go：以微服务方式驱动 Restic/Kopia 完成卷数据上传与回放。

需要注意的是，v0.9.4 的具体二进制能力属于历史版本事实；当前仓库主线已将底层实现演进为统一的 uploader 抽象（见 pkg/uploader），但这不妨碍我们从历史版本的角度理解 v0.11 引入多线程恢复的里程碑意义。

重大变更三：恢复流程等待资源删除完成

变更背景

在 v0.11 之前，恢复（restore）流程在目标集群中遇到正在被删除的命名空间（terminating namespace）或持久卷（terminating PV）时，会直接尝试恢复这些资源，结果往往因资源仍处于终止状态而失败。

变更内容

v0.11.0 修复了这一问题（#826, @nrb）：Velero 现在会等待处于 terminating 状态的命名空间和持久卷彻底删除之后，再尝试恢复它们，避免"边删边建"造成的冲突与失败。

这一改动虽然从 changelog 看只是一行，但它在恢复健壮性上意义重大——它让"先清理、后重建"这类常见恢复场景（例如整集群迁移）变得可靠。从当前仓库的结构看，恢复流程的资源协调逻辑集中在 pkg/restore/restore.go 及其配套的 pkg/restore/request.go 中，历史版本的"等待删除"逻辑正是在这条链路上引入的。

重大变更四：备份压缩包新增 backup-version 版本文件

变更内容

v0.11.0 在备份生成的 tarball 中新增了 backup-version 文件（#1117, @wwitzel3），用于记录备份数据自身的版本信息。这是 Velero 对备份数据格式进行版本化管理的开端——后续版本读取备份 tarball 时，可以依据该文件判断备份格式的兼容性。

当前源码中的直接继承

这一机制在当前仓库中依然存在，且演进为更完整的版本常量。在 pkg/backup/backup.go 中可以找到：

// BackupVersion is the current backup major version for Velero.
// Deprecated, use BackupFormatVersion
const BackupVersion = 1

// BackupFormatVersion is the current backup version for Velero, including major, minor, and patch.
const BackupFormatVersion = "1.1.0"

其中 BackupVersion 正是 v0.11 引入的"备份主版本号"的直接后代，只是当前仓库已将其标记为 Deprecated，改用包含 major.minor.patch 的完整格式版本 BackupFormatVersion。

而写入备份 tarball 的实现位于 pkg/backup/backup.go 的 writeBackupVersion 函数：

func (kb *kubernetesBackupper) writeBackupVersion(tw tarWriter) error {
	versionFile := filepath.Join(velerov1api.MetadataDir, "version")
	versionString := fmt.Sprintf("%s\n", BackupFormatVersion)
	// ... 将版本文件写入 tar
}

可以看到，当前实现将版本信息写入备份压缩包内 metadata/version 路径（对应历史版本 tarball 中的 backup-version 文件），并在 pkg/controller/backup_controller.go 中参与备份的组装流程。这从源码层面印证了 v0.11 引入的"备份版本文件"机制如何在 Velero 中沉淀为备份格式兼容性管理的基础设施。

重大变更五：新增 ServerStatusRequest CRD，支撑服务端版本查询

变更内容

v0.11.0 新增了 ServerStatusRequest 自定义资源（#1116, @skriss），并让 ark version（更名后为 velero version）命令能够同时显示客户端与服务端版本信息。此前 CLI 只能获取客户端自身的版本，无法知晓集群内 Velero server 的运行版本；通过创建 ServerStatusRequest 资源并等待控制器处理，CLI 可以拿到服务端的版本号与插件列表。

当前源码中的类型定义

ServerStatusRequest 的类型在当前仓库中依然完整保留，见 pkg/apis/velero/v1/server_status_request_types.go：

• 资源经历 New → Processed 两个生命周期阶段（ServerStatusRequestPhase）；
• 状态字段（ServerStatusRequestStatus）包含：
  • phase：请求处理阶段；
  • processedTimestamp：控制器处理完成的时间；
  • serverVersion：Velero 服务端版本号；
  • plugins：服务端当前加载的插件信息（名称与类型）。

其 CRD 注册位于 pkg/apis/velero/v1/register.go，对应的 RBAC 权限（对 serverstatusrequests 的 get/list/watch/create/update/patch/delete）在该类型文件的 kubebuilder 标记中也有明确声明。配套的控制器与 CLI 集成可分别参考 pkg/controller/server_status_request_controller.go 与 pkg/cmd/cli/version 目录下的实现。

补充变更一览

除上述五大变更外，v0.11.0 还包含以下细节改进（均记录于 changelog）：

变更	说明
修复 restic 仓库存在性判断的并发 bug（#1235, @skriss）	多个备份并发执行时，确保"确保 restic 仓库存在"的代码路径不产生竞态
GCP 区域磁盘（regional disk）恢复时设置 zones（#1200, @nrb）	需要在 GCP 服务账号上授予 compute.zones.get 权限才能正常工作
对象无变化时澄清恢复日志（#1153, @daved）	当备份中的对象与目标集群中现有对象一致时，输出更清晰的日志，避免误导

v0.11.1 实战：用 velero migrate-backups 迁移 Ark 备份元数据

为什么需要这个命令

v0.11.1 发布的核心动机，是为升级到 v1.0 做准备。官方给出的升级约束是：不能从 v0.10.x 或更早版本直接升级到 v1.0，必须先经过 v0.11（详见仓库内的 site/content/docs/v1.0.0/upgrade-to-1.0.md）。

原因在于：任何最初由 Ark（v0.11 之前）创建的备份，其元数据格式与 v1.0 不兼容。v0.11 仍可向后兼容读取这些旧文件，但 v1.0 不再兼容。因此，在升级到 v1.0 之前，必须使用 v0.11.1 提供的 velero migrate-backups 命令，将对象存储中的历史备份元数据重写为新格式。

velero migrate-backups 命令具体完成两件事：

1. 将对象存储中的 ark-backup.json 文件替换为等价的 velero-backup.json 文件；
2. 为每个备份创建 <backup-name>-volumesnapshots.json.gz 文件（若不存在），其中的快照元数据取自该备份的 status.volumeBackups 字段。

其中第二点的背景是：v0.10 之前创建的备份把快照元数据存放在 status.volumeBackups 字段中，而该字段后续已被独立的 <backup-name>-volumesnapshots.json.gz 文件取代。迁移命令负责把这段历史遗留数据"落盘"成新的标准文件。

前提：如果你确认自己的备份全部是在 v0.11 及之后创建的（即从未使用过 Ark），可以直接跳过元数据重写步骤。

完整操作步骤

以下步骤来自仓库内的官方升级指南 site/content/docs/v1.0.0/upgrade-to-1.0.md，在此完整保留并整理：

1. 准备 v0.11.1 客户端与临时凭证

下载 v0.11.1 的 release tarball，解压并将 velero 二进制放入 PATH：

tar -xvf <RELEASE-TARBALL-NAME>.tar.gz -C /dir/to/extract/to

强烈建议先对 Velero 使用的对象存储 bucket 做一份完整副本——第 1 部分升级流程会修改 bucket 内容，备份副本可在出错时回滚。

2. 缩容 Velero deployment

kubectl -n velero scale deployment/velero --replicas 0

迁移期间停止 Velero server，避免它在迁移元数据的同时读写对象存储。

3. 导出对象存储访问凭证到本地

从 cloud-credentials Secret 中导出凭证，供 velero migrate-backups 命令行工具直接访问对象存储。

AWS：

export AWS_SHARED_CREDENTIALS_FILE=./velero-migrate-backups-credentials
kubectl -n velero get secret cloud-credentials -o jsonpath="{.data.cloud}" | base64 --decode > $AWS_SHARED_CREDENTIALS_FILE

Azure：

export AZURE_SUBSCRIPTION_ID=$(kubectl -n velero get secret cloud-credentials -o jsonpath="{.data.AZURE_SUBSCRIPTION_ID}" | base64 --decode)
export AZURE_TENANT_ID=$(kubectl -n velero get secret cloud-credentials -o jsonpath="{.data.AZURE_TENANT_ID}" | base64 --decode)
export AZURE_CLIENT_ID=$(kubectl -n velero get secret cloud-credentials -o jsonpath="{.data.AZURE_CLIENT_ID}" | base64 --decode)
export AZURE_CLIENT_SECRET=$(kubectl -n velero get secret cloud-credentials -o jsonpath="{.data.AZURE_CLIENT_SECRET}" | base64 --decode)
export AZURE_RESOURCE_GROUP=$(kubectl -n velero get secret cloud-credentials -o jsonpath="{.data.AZURE_RESOURCE_GROUP}" | base64 --decode)

GCP：

export GOOGLE_APPLICATION_CREDENTIALS=./velero-migrate-backups-credentials
kubectl -n velero get secret cloud-credentials -o jsonpath="{.data.cloud}" | base64 --decode > $GOOGLE_APPLICATION_CREDENTIALS

4. 列出所有 BackupStorageLocation

velero backup-location get

5. 对每个备份存储位置执行迁移

# BACKUP_LOCATION_NAME：上一步列出的、需要升级的备份存储位置名称
# SNAPSHOT_LOCATION_NAME：Velero 记录卷快照归属的 VolumeSnapshotLocation 名称
#   （仅当存在 v0.10 之前由 Ark/Velero 创建的备份时才相关）
velero migrate-backups \
    --backup-location <BACKUP_LOCATION_NAME> \
    --snapshot-location <SNAPSHOT_LOCATION_NAME>

对每个计划在 Velero 1.0 中继续使用的备份存储位置，依次执行上述命令。

6. 恢复 Velero deployment 并清理本地凭证

kubectl -n velero scale deployment/velero --replicas 1

清理步骤按云平台分别执行：

AWS：

rm $AWS_SHARED_CREDENTIALS_FILE
unset AWS_SHARED_CREDENTIALS_FILE

Azure：

unset AZURE_SUBSCRIPTION_ID
unset AZURE_TENANT_ID
unset AZURE_CLIENT_ID
unset AZURE_CLIENT_SECRET
unset AZURE_RESOURCE_GROUP

GCP：

rm $GOOGLE_APPLICATION_CREDENTIALS
unset GOOGLE_APPLICATION_CREDENTIALS

迁移完成后的 v1.0 组件升级

元数据重写完成后，可进入 v1.0 组件升级阶段：下载 v1.0 release tarball、替换本地 velero 二进制，并更新集群内镜像：

kubectl -n velero set image deployment/velero velero=gcr.io/heptio-images/velero:v1.0.0
kubectl -n velero set image daemonset/restic restic=gcr.io/heptio-images/velero:v1.0.0

说明：velero migrate-backups 命令由 v0.11.1 引入，用于一次性完成 Ark 遗留元数据重写；在后续版本中该历史功能已随旧格式的淘汰而淡出主线。当前仓库已无法找到该命令的源码实现，本文步骤完全依据仓库内保留的官方升级文档 site/content/docs/v1.0.0/upgrade-to-1.0.md 整理，可放心对照执行。

总结

回顾 v0.11 这个版本，可以清晰地看到它在 Velero 演进史上的"分水岭"角色：

1. 命名与生态层面：完成 Heptio Ark → Velero 的更名，确立沿用至今的项目品牌与二进制/镜像命名；
2. 性能层面：Restic 0.9.4 引入多线程恢复，卷数据恢复速度大幅提升；
3. 健壮性层面：恢复流程等待 terminating 资源删除，修复了一类高频恢复失败场景；
4. 数据格式层面：备份 tarball 引入版本文件，为备份格式的向后/向前兼容管理奠定基础；新增 ServerStatusRequest CRD，让 CLI 能够感知服务端版本与插件状态；
5. 升级路径层面：v0.11.1 的 velero migrate-backups 打通了 Ark 时代数据通往 v1.0 的唯一官方通道。

对于运维 Ark/Velero 历史集群的团队，v0.11 最值得记住的实操结论是：升级到 v1.0 前，务必确认是否存在 Ark 时期创建的备份，若有则必须先经 v0.11 并用 velero migrate-backups 完成元数据重写，否则旧备份将在 v1.0 中变得不可读取。