Harvester 存储迁移机制全解析:借助 KubeVirt 在线迁移跨 StorageClass 搬迁 VM 卷
Harvester 存储迁移机制全解析:借助 KubeVirt 在线迁移跨 StorageClass 搬迁 VM 卷
Harvester 作为开源超融合基础设施(HCI)软件,支持 Longhorn、LVM 与第三方存储等多种存储后端。本指南围绕其 Storage Migration(存储迁移)增强提案,系统讲解如何在不显著中断业务的前提下,将 VM 卷从一个 StorageClass 在线迁移到另一个 StorageClass:从 harvesterhci.io/volumeClaimTemplates 注解的 targetVolume 字段、VM Controller 的两阶段状态机,到 Webhook 准入校验、REST API 操作与故障处理,并给出仓库源码级的实现佐证。读完本文,你将掌握在 Harvester 中配置与触发卷在线迁移、理解迁移失败与取消的恢复语义,以及判断哪些磁盘类型不可迁移的完整实战知识。
背景与动机:为什么要做存储迁移
Harvester 支持多种存储后端,这给用户带来了灵活性的同时,也带来了"存量数据搬家"的需求。典型场景包括:
- 从本地存储迁往副本存储以获得高可用:VM 运行在 LVM 本地存储上,而 VM 若要跨节点在线迁移(live migration),KubeVirt 要求使用具备副本能力的存储(如 Longhorn),此时需要把卷搬到 Longhorn。
- 接入第三方存储后搬迁存量卷:用户已将 Ceph、NetApp 等第三方存储方案接入 Harvester,希望把既有 VM 卷平滑迁往新后端,而无需关机复制数据。
目标与非目标
该增强提案明确的目标如下:
- 允许用户将一个 VM 卷从一个 StorageClass 迁移到另一个 StorageClass;
- 仅实现在线存储迁移,离线(VM 关机)迁移行为保持不变;
- 提供文档说明推荐的离线(VM 断电)迁移流程,但不引入新的离线迁移特性;
- 在 PersistentVolumeClaim 之上引入 DataVolume 层,以支持多种存储厂商并支撑存储迁移能力。
同时明确划出边界:跨集群的存储迁移不在范围内。
用户故事
- Story 1:从本地存储迁往副本存储以启用 HA。用户的 VM 运行在 LVM 本地存储上,现在需要为 VM 开启在线迁移能力(这要求副本存储),希望将卷迁到 Longhorn 副本存储,使 VM 能在节点间在线迁移。
- Story 2:迁移到第三方存储。用户已将第三方存储方案集成进 Harvester,希望不停机地把既有 VM 卷迁移到新存储后端上。
用户操作体验
一次完整的存储迁移在用户侧呈现为如下流程:
- 用户创建目标卷——一个带有目标 StorageClass 的新 PVC;
- 用户进入 VM 详情页,选择要迁移的卷;
- 系统校验迁移可行性(例如目标存储的容量是否充足);
- 用户确认迁移,系统随即启动迁移:发起 VM 在线迁移,同时在后台复制卷数据;
- 迁移完成后,VM 自动使用新卷。
需要说明的是,存储迁移本质上构建在 KubeVirt 的 VM 在线迁移之上,但由于存储迁移需要把整个卷的数据拷贝到目标卷,其耗时可能远超普通的 VM 在线迁移——具体时长取决于卷大小与存储性能。
高层面架构与 DataVolume 抽象层
存储迁移的整体架构如下图所示:
架构的核心思路是:复用 KubeVirt 的 volume migration(卷迁移)能力,并通过 CDI(Containerized Data Importer)的 DataVolume 作为卷管理的最顶层抽象。迁移时系统创建一个指向目标 PVC 的新 DataVolume,DataVolume 提供了一层抽象,使得不同存储后端之间的数据拷贝(克隆)可以无缝进行——这正是跨厂商、跨 StorageClass 迁移得以成立的关键。
整个实现可以概括为两大步骤:
- 新 API 字段:在
harvesterhci.io/volumeClaimTemplates注解中扩展可选的targetVolume字段,指明迁移目标 PVC; - VM Controller 增强:检测到某个卷带有
targetVolume时,在 VM 在线迁移过程中触发存储迁移流程。
VM Controller 会更新 VM spec 中的以下字段:
- 更新
spec.template.spec.volumes使其引用新的存储后端,且遵循明确的优先级规则:- 当迁移流程已经为
targetVolumePVC 创建或关联了 DataVolume(例如集群中存在拥有或引用该目标 PVC 的 DataVolume CR)时,优先使用dataVolume卷源,将volume.dataVolume.name设置为该 DataVolume 名称; - 当目标卷不存在这样的 DataVolume 时,回退使用
persistentVolumeClaim卷源,将volume.persistentVolumeClaim.claimName设置为targetVolumePVC 名称;
- 当迁移流程已经为
- 将
updateVolumesStrategy更新为Migration,以触发迁移过程。
API 变更:volumeClaimTemplates 注解与 targetVolume 字段
Go 类型定义
存储迁移复用了 VirtualMachine CR 上已有的 harvesterhci.io/volumeClaimTemplates 注解。该注解的值是一个 VolumeClaimTemplateEntry 对象的 JSON 数组,每个条目新增一个可选的 targetVolume 字段。其 Go 类型定义如下(对应 pkg/util/volume.go):
// VolumeClaimTemplateEntry represents a single entry in the volumeClaimTemplates annotation.
// PVC fields are inlined so access patterns remain the same as the legacy []PVC format.
// The optional TargetVolume field is used for storage migration.
type VolumeClaimTemplateEntry struct {
corev1.PersistentVolumeClaim `json:",inline"`
TargetVolume string `json:"targetVolume,omitempty"`
}
关键设计点:
PersistentVolumeClaim字段被内联(inline),因此每个条目直接包含标准 PVC 的metadata与spec,与既有格式保持一致;targetVolume(可选):卷要迁往的新 PVC 名称。当该字段被设置时,系统会在 VM 在线迁移期间对该卷触发存储迁移;未设置时卷保持不变。
仓库还提供了配套的序列化与反序列化工具函数:UnmarshalVolumeClaimTemplates 将注解字符串解析为条目切片(并天然兼容旧的 <a href="https://link.gitcode.com/i/e75e154139c6da2eff98ead76dcbe1c5" target="_blank">]PVC 格式),MarshalVolumeClaimTemplates 将条目序列化回 JSON,GetPVCsFromVolumeClaimTemplates 可从条目中提取 PVC 列表,三者均位于 [pkg/util/volume.go。
注解值示例
[
{
"metadata": {
"name": "my-vol",
"annotations": {
"harvesterhci.io/imageId": ""
}
},
"spec": {
"accessModes": ["ReadWriteMany"],
"resources": {
"requests": {
"storage": "10Gi"
}
},
"storageClassName": "longhorn",
"volumeMode": "Block"
},
"targetVolume": "my-vol-target"
}
]
该示例表达:将 VM 卷 my-vol(当前位于 longhorn StorageClass、10Gi、Block 模式)在线迁移到新 PVC my-vol-target。
实现原理:VM Controller 的两阶段状态机
存储迁移的核心状态机由 VM Controller 上的两个处理器协作完成,二者分别注册为 VMController.SetTargetVolumeStrategy 与 VMController.CleanupTargetVolumeAnnotation(见 pkg/controller/master/virtualmachine/register.go),测试用例 TestSetTargetVolumeStrategy 与 TestCleanupTargetVolumeAnnotation 位于 pkg/controller/master/virtualmachine/vm_controller_test.go。
阶段一:SetTargetVolumeStrategy —— 发起迁移
SetTargetVolumeStrategy(pkg/controller/master/virtualmachine/vm_controller.go)负责识别注解中的 targetVolume 条目并改写 VM spec,以触发 KubeVirt 卷迁移:
- 读取 VM 注解
harvesterhci.io/volumeClaimTemplates,若不存在或为空则直接返回; - 解析条目并收集映射表
targetVolumes: 旧 PVC 名 -> 新 PVC 名;若没有任何条目带有targetVolume,直接返回; - 遍历
vm.Spec.Template.Spec.Volumes,通过getVolumeBackingRef取出每个卷背后的 PVC 名与 hotpluggable 标记(getVolumeBackingRef仅识别PersistentVolumeClaim卷源,oldName为空表示非 PVC 卷,跳过); - 对命中映射的卷,用
buildPVCVolumeSource(newName, hotpluggable)将其卷源替换为目标 PVC; - 将
spec.UpdateVolumesStrategy设置为kubevirtv1.UpdateVolumesStrategyMigration; - 首次更新时同时写入等待注解
harvesterhci.io/waitingStorageMigration: "true",然后vmClient.Update。
后续的 clearMigrationWait 逻辑负责"等待真正进入迁移态":当 Status.PrintableStatus 为 Migrating 时删除等待注解,否则对 VM 做 requeue 继续等待——这保证控制器不会在 KubeVirt 尚未开始迁移时就进入清理流程。
阶段二:CleanupTargetVolumeAnnotation —— 收尾迁移
CleanupTargetVolumeAnnotation(pkg/controller/master/virtualmachine/vm_controller.go)在迁移完成后做注解收尾。它判定"迁移完成"必须同时满足三个条件:
- 注解条目中带有非空的
targetVolume字段; - VM spec 卷已指向
targetVolume名称; - VM 不存在
VolumesChange条件(VirtualMachineInstanceVolumesChange == True,表明迁移已结束)。
此外还会跳过"存储迁移尚在等待开始"(存在 waitingStorageMigration 注解)以及 VM 尚未回到 Running 的状态。条件全部满足后,finalizeCompletedMigrations(pkg/controller/master/virtualmachine/vm_controller.go)执行最终处理:
- 从 PVC cache 获取真实的目标 PVC;
- 将该条目的内联 PVC 字段(metadata 名称与注解、accessModes、resources、volumeMode、storageClassName)替换为目标 PVC 的实际信息;
- 将
TargetVolume清空; - 序列化回注解并更新 VM。
这样迁移完成后,注解中的该卷就"永久"切换到了新 PVC,targetVolume 字段被消费掉,不再残留迁移状态。
Webhook 准入校验:什么情况下允许迁移
Harvester 的 admission webhook 会在 API 层面对 targetVolume 配置做严格校验(checkTargetVolumes 与 validateTargetVolumeEntry,见 pkg/webhook/resources/virtualmachine/validator.go),对应测试 TestCheckTargetVolumes 见 pkg/webhook/resources/virtualmachine/validator_test.go。校验规则如下:
| 校验项 | 规则 | 被拒原因 |
|---|---|---|
| 并发迁移 | 同一时刻仅允许一个卷迁移 | only one volume migration is allowed at a time |
| 条目完整性 | 设置 targetVolume 时 PVC 内容不能为空 |
PVC content must not be empty when targetVolume is set |
| 源类型 | 源卷必须是 PVC 卷源 | source volume ... is a DataVolume, only PVC sources are supported for storage migration |
| 源挂载状态 | 源 PVC 必须已挂载到 VM | PVC ... is not attached to the VM |
| VM 状态 | VM 必须是运行态 | VM must be running to set targetVolume for volume migration |
| 目标存在性 | 目标 PVC 必须已存在于同一命名空间 | targetVolume PVC ... not found |
| 容量约束 | 目标卷容量不得小于源卷 | targetVolume ... size (...) must not be less than source volume ... size (...) |
其中"迁移已在进行中"(VM spec 卷已指向 targetVolume)时会直接放行,避免重复校验。上述规则与测试用例一一对应,例如 pkg/webhook/resources/virtualmachine/validator_test.go 验证"目标 PVC 不存在被拒绝"、pkg/webhook/resources/virtualmachine/validator_test.go 验证"多个 targetVolume 同时设置被拒绝"、pkg/webhook/resources/virtualmachine/validator_test.go 验证"目标容量小于源容量被拒绝"。
用户操作路径:UI 与 REST API
UI 操作路径
用户既可以通过 UI 触发迁移(在 VM 详情页选择卷并为该卷指定目标 PVC),也可以通过 API 直接操作。UI 侧背后同样是"创建目标 PVC + 在注解中写入 targetVolume"的同一套机制。
REST API:触发与取消迁移
pkg/api/vm/handler.go 为 VM 提供了两个 action:storageMigration 与 cancelStorageMigration(见 pkg/api/vm/handler.go),其输入结构 StorageMigrationInput 定义于 pkg/api/vm/types.go:
type StorageMigrationInput struct {
SourceVolume string `json:"sourceVolume"`
TargetVolume string `json:"targetVolume"`
}
触发迁移(storageMigration,见 pkg/api/vm/handler.go)的流程是:
- 从 cache 读取 VM;
- 解析
volumeClaimTemplates注解; - 在条目中找到
entry.Name == input.SourceVolume的卷,设置entries[i].TargetVolume = input.TargetVolume; - 重新序列化注解并更新 VM。
其中还校验 sourceVolume 与 targetVolume 均必填且不能相同(见 pkg/api/vm/handler.go)。注解更新后,webhook 会先做准入校验,随后 VM Controller 的 SetTargetVolumeStrategy 接手推进迁移。
取消迁移(cancelStorageMigration,见 pkg/api/vm/handler.go)的流程是:
- 解析注解,从所有带
targetVolume的条目构建targetVolume -> sourceVolume反向映射,并清空各条目的targetVolume; - 若不存在活跃迁移,返回
no active storage migration found; - 遍历
vm.Spec.Template.Spec.Volumes,把仍指向目标 PVC 的卷源恢复回源 PVC(保留 hotpluggable 标记); - 删除
waitingStorageMigration注解并将UpdateVolumesStrategy置空; - 更新 VM。
这一流程对应原提案"错误处理-取消"一节:中止 VM 在线迁移 → VM 继续使用原卷运行(无数据丢失)→ 控制器清空注解中的 targetVolume 字段。目标 PVC 不会自动清理,若不再需要由用户自行删除。
卷的 DataVolume 数据迁移 action
在卷(volume)资源侧,pkg/api/volume/handler.go 提供了 dataMigration action(pkg/api/volume/handler.go),它直接创建一个以源 PVC 为来源、以目标 StorageClass 为目标的 CDI DataVolume,实现纯数据层面的克隆搬迁:
dv := &cdiv1.DataVolume{
ObjectMeta: metav1.ObjectMeta{
Name: input.TargetVolumeName,
Namespace: pvcNamespace,
},
Spec: cdiv1.DataVolumeSpec{
Source: &cdiv1.DataVolumeSource{
PVC: &cdiv1.DataVolumeSourcePVC{
Name: pvcName,
Namespace: pvcNamespace,
},
},
Storage: &cdiv1.StorageSpec{
StorageClassName: &input.TargetStorageClassName,
Resources: corev1.VolumeResourceRequirements{
Requests: pvc.Spec.Resources.Requests,
},
},
},
}
其前置校验(validateDataMigration,pkg/api/volume/handler.go)确保:源 PVC 存在、目标 StorageClass 存在、目标 PVC 与 DataVolume 均未占用(同名已存在则拒绝)、源 PVC 当前未被使用(assertPVCNotInUse)。这正是提案中"DataVolume 引入抽象层、实现不同存储后端间无缝克隆"在 API 层的落地。
错误处理与恢复语义
取消(Cancellation)
用户在 UI 或 API 触发取消后:
- 控制器中止正在进行的 VM 在线迁移;
- VM 继续使用原卷运行,数据不丢失;
- 控制器清空注解中的
targetVolume字段; - 目标 PVC 不做自动清理,用户按需自行删除。
迁移失败(Migration Failure)
当存储迁移失败(如目标存储空间不足、网络错误、节点故障)时:
- KubeVirt 自动重试 VM 在线迁移;
- 重试循环持续进行,直到迁移成功或用户显式取消;
- 用户需通过取消流程来停止重试;
- 控制器更新 VM 状态/条件以反映失败原因,便于用户排查。
手动恢复(Manual Recovery)
当卷迁移以需要人工介入的方式失败时,KubeVirt 会在 VirtualMachine CR 上设置 ManualRecoveryRequired 条件。UI 应向用户展示对应提示信息,同时应提供相关文档说明如何解决该问题并清除该条件。
限制:哪些场景不支持在线存储迁移
以下限制继承自 KubeVirt 的卷迁移能力,配置前需重点确认:
| 限制项 | 说明 |
|---|---|
| 可共享磁盘(Shareable disks) | 不支持,多个写入者会导致数据一致性问题 |
| 热插拔磁盘(Hotpluggable disks) | 不可迁移 |
| virtiofs 磁盘 | 不支持,缺少在线迁移能力 |
| LUN 磁盘 | 当目标 StorageClass 与源不同时不可迁移 |
| 同节点迁移 | 卷迁移要求 VM 迁移到不同节点,同节点存储迁移不支持 |
| 本地存储上的 RWO PVC 对 | 仅在两个 PVC 位于不同节点时允许互迁 |
| 迁移源类型 | 仅支持 PersistentVolumeClaim 与 DataVolume 作为迁移源 |
| 不支持的磁盘类型 | 会收到 RestartRequired 条件,卷在 VM 重启时被替换而非在线迁移期间替换 |
向后兼容与升级策略
由于 targetVolume 是全新可选字段:未设置该字段的既有 VM 将完全照旧工作,存储迁移功能整体是 opt-in 的,因此对现有用户没有任何破坏性变更。升级流程同样无需改动——新迁移特性不影响既有功能。参考 enhancements/20260224-storage-migration.md 中 Backwards Compatibility 与 Upgrade strategy 两节。
测试计划:如何验证存储迁移
仓库内已提供覆盖控制器与校验器的单元测试(见上文各测试文件),功能验证可参考如下测试计划:
在线迁移测试:
- 在源 StorageClass 上创建带卷的 VM;
- 以目标 StorageClass 创建新 PVC;
- 方式一:直接更新 VM 的
harvesterhci.io/volumeClaimTemplates注解,为卷加上指向新 PVC 的targetVolume字段;方式二:使用 UI 选择目标 PVC 触发迁移; - 验证迁移进程启动并成功完成,VM 自动切换到新卷。
取消测试:搭建上述迁移场景后在迁移中途取消,确保 VM 继续以原卷运行且无数据丢失。
失败测试:搭建上述迁移场景后在迁移中途模拟失败,确保一切回滚到原始状态,VM 仍能基于原卷正常工作。
小结
Harvester 的存储迁移机制以 harvesterhci.io/volumeClaimTemplates 注解的 targetVolume 字段为入口,通过 VM Controller 的 SetTargetVolumeStrategy/CleanupTargetVolumeAnnotation 两阶段状态机驱动 KubeVirt 卷迁移,并以 CDI DataVolume 作为跨后端克隆的抽象层,最终实现了"不停机、从一种 StorageClass 迁往另一种 StorageClass"的能力。结合 Webhook 的准入校验、REST API 的触发/取消动作以及完善的错误恢复语义,该特性覆盖了从本地存储迁往副本存储、接入第三方存储等核心运维场景;同时,其 opt-in 设计与明确的限制清单(共享盘、热插拔盘、virtiofs、LUN 等不可在线迁移)也为生产环境的评估与规划提供了清晰依据。相关实现细节可继续阅读 pkg/util/volume.go、pkg/controller/master/virtualmachine/vm_controller.go 与 pkg/webhook/resources/virtualmachine/validator.go。
