Harvester 存储迁移机制全解析:借助 KubeVirt 在线迁移跨 StorageClass 搬迁 VM 卷

原创2026-10-13 14:24:18464 阅读
文章标签:云原生虚拟化容器编排集群管理后端存储高可用

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 卷迁移到新存储后端上。

用户操作体验

一次完整的存储迁移在用户侧呈现为如下流程:

  1. 用户创建目标卷——一个带有目标 StorageClass 的新 PVC;
  2. 用户进入 VM 详情页,选择要迁移的卷;
  3. 系统校验迁移可行性(例如目标存储的容量是否充足);
  4. 用户确认迁移,系统随即启动迁移:发起 VM 在线迁移,同时在后台复制卷数据;
  5. 迁移完成后,VM 自动使用新卷。

需要说明的是,存储迁移本质上构建在 KubeVirt 的 VM 在线迁移之上,但由于存储迁移需要把整个卷的数据拷贝到目标卷,其耗时可能远超普通的 VM 在线迁移——具体时长取决于卷大小与存储性能。

高层面架构与 DataVolume 抽象层

存储迁移的整体架构如下图所示:

Harvester 存储迁移架构图:VM 卷经 DataVolume/PVC 层在源存储类与目标存储类之间搬迁

架构的核心思路是:复用 KubeVirt 的 volume migration(卷迁移)能力,并通过 CDI(Containerized Data Importer)的 DataVolume 作为卷管理的最顶层抽象。迁移时系统创建一个指向目标 PVC 的新 DataVolume,DataVolume 提供了一层抽象,使得不同存储后端之间的数据拷贝(克隆)可以无缝进行——这正是跨厂商、跨 StorageClass 迁移得以成立的关键。

整个实现可以概括为两大步骤:

  1. 新 API 字段:在 harvesterhci.io/volumeClaimTemplates 注解中扩展可选的 targetVolume 字段,指明迁移目标 PVC;
  2. VM Controller 增强:检测到某个卷带有 targetVolume 时,在 VM 在线迁移过程中触发存储迁移流程。

VM Controller 会更新 VM spec 中的以下字段:

  • 更新 spec.template.spec.volumes 使其引用新的存储后端,且遵循明确的优先级规则:
    • 当迁移流程已经为 targetVolume PVC 创建或关联了 DataVolume(例如集群中存在拥有或引用该目标 PVC 的 DataVolume CR)时,优先使用 dataVolume 卷源,将 volume.dataVolume.name 设置为该 DataVolume 名称;
    • 当目标卷不存在这样的 DataVolume 时,回退使用 persistentVolumeClaim 卷源,将 volume.persistentVolumeClaim.claimName 设置为 targetVolume PVC 名称;
  • 将 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 卷迁移:

  1. 读取 VM 注解 harvesterhci.io/volumeClaimTemplates,若不存在或为空则直接返回;
  2. 解析条目并收集映射表 targetVolumes: 旧 PVC 名 -> 新 PVC 名;若没有任何条目带有 targetVolume,直接返回;
  3. 遍历 vm.Spec.Template.Spec.Volumes,通过 getVolumeBackingRef 取出每个卷背后的 PVC 名与 hotpluggable 标记(getVolumeBackingRef 仅识别 PersistentVolumeClaim 卷源,oldName 为空表示非 PVC 卷,跳过);
  4. 对命中映射的卷,用 buildPVCVolumeSource(newName, hotpluggable) 将其卷源替换为目标 PVC;
  5. 将 spec.UpdateVolumesStrategy 设置为 kubevirtv1.UpdateVolumesStrategyMigration;
  6. 首次更新时同时写入等待注解 harvesterhci.io/waitingStorageMigration: "true",然后 vmClient.Update。

后续的 clearMigrationWait 逻辑负责"等待真正进入迁移态":当 Status.PrintableStatus 为 Migrating 时删除等待注解,否则对 VM 做 requeue 继续等待——这保证控制器不会在 KubeVirt 尚未开始迁移时就进入清理流程。

阶段二:CleanupTargetVolumeAnnotation —— 收尾迁移

CleanupTargetVolumeAnnotation(pkg/controller/master/virtualmachine/vm_controller.go)在迁移完成后做注解收尾。它判定"迁移完成"必须同时满足三个条件:

  1. 注解条目中带有非空的 targetVolume 字段;
  2. VM spec 卷已指向 targetVolume 名称;
  3. 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)的流程是:

  1. 从 cache 读取 VM;
  2. 解析 volumeClaimTemplates 注解;
  3. 在条目中找到 entry.Name == input.SourceVolume 的卷,设置 entries[i].TargetVolume = input.TargetVolume;
  4. 重新序列化注解并更新 VM。

其中还校验 sourceVolume 与 targetVolume 均必填且不能相同(见 pkg/api/vm/handler.go)。注解更新后,webhook 会先做准入校验,随后 VM Controller 的 SetTargetVolumeStrategy 接手推进迁移。

取消迁移(cancelStorageMigration,见 pkg/api/vm/handler.go)的流程是:

  1. 解析注解,从所有带 targetVolume 的条目构建 targetVolume -> sourceVolume 反向映射,并清空各条目的 targetVolume;
  2. 若不存在活跃迁移,返回 no active storage migration found;
  3. 遍历 vm.Spec.Template.Spec.Volumes,把仍指向目标 PVC 的卷源恢复回源 PVC(保留 hotpluggable 标记);
  4. 删除 waitingStorageMigration 注解并将 UpdateVolumesStrategy 置空;
  5. 更新 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 触发取消后:

  1. 控制器中止正在进行的 VM 在线迁移;
  2. VM 继续使用原卷运行,数据不丢失;
  3. 控制器清空注解中的 targetVolume 字段;
  4. 目标 PVC 不做自动清理,用户按需自行删除。

迁移失败(Migration Failure)

当存储迁移失败(如目标存储空间不足、网络错误、节点故障)时:

  1. KubeVirt 自动重试 VM 在线迁移;
  2. 重试循环持续进行,直到迁移成功或用户显式取消;
  3. 用户需通过取消流程来停止重试;
  4. 控制器更新 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 两节。

测试计划:如何验证存储迁移

仓库内已提供覆盖控制器与校验器的单元测试(见上文各测试文件),功能验证可参考如下测试计划:

在线迁移测试:

  1. 在源 StorageClass 上创建带卷的 VM;
  2. 以目标 StorageClass 创建新 PVC;
  3. 方式一:直接更新 VM 的 harvesterhci.io/volumeClaimTemplates 注解,为卷加上指向新 PVC 的 targetVolume 字段;方式二:使用 UI 选择目标 PVC 触发迁移;
  4. 验证迁移进程启动并成功完成,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。

登录后查看全文
harvester