Harvester KubeVirt 迁移设置(kubevirt-migration)全解析:UI 配置、Webhook 校验与控制器同步机制

原创2026-10-12 12:03:051,429 阅读
文章标签:云原生虚拟化容器编排集群管理后端存储高可用

Harvester KubeVirt 迁移设置(kubevirt-migration)全解析:UI 配置、Webhook 校验与控制器同步机制

导读

Harvester 是一款开源的超融合基础设施(HCI)软件,其底层使用 KubeVirt 运行虚拟机。当集群中虚拟机数量增多、需要批量迁移(例如节点维护、升级、故障处理)时,KubeVirt 默认的迁移参数往往无法满足实际吞吐需求。本文围绕 Harvester 仓库中的增强设计文档 enhancements/20250922-kubevirt-migration-setting.md,深入剖析 Harvester 如何将 KubeVirt 迁移配置以 kubevirt-migration 设置的形式暴露到 UI,并完整讲解其默认参数、Webhook 校验规则、Controller 同步链路以及"受保护字段"(nodeDrainTaintKey、network)的设计原因。读完本文,你将掌握如何安全地通过 Harvester 调优并行迁移数、带宽等关键参数,并理解为什么某些字段不能被直接修改。

一、为什么 Harvester 需要暴露 KubeVirt 迁移设置

KubeVirt 本身提供了丰富的迁移(Live Migration)配置,例如并行迁移数量、单次迁移带宽上限、超时时间等。在引入该 HEP 之前,用户若想调整这些参数,只能直接修改 KubeVirt 的 KubeVirt CR(Custom Resource),操作门槛高且容易误改关键字段。

该 HEP 的目标(见 原设计文档 的 Goals 小节)非常明确:

  1. 将 KubeVirt 迁移配置暴露为 Harvester 的 kubevirt-migration 设置,用户可在 Harvester UI 上直接查看与修改;
  2. 不得破坏升级脚本:升级脚本依赖 nodeDrainTaintKey,因此该字段不允许用户修改;
  3. 不得覆盖网络配置:迁移网络(migration network)由独立的 vm-migration-network 设置管理,kubevirt-migration 中的 network 字段被忽略。

同时,该 HEP 明确标注 API changes: N/A,即不会引入新的 Harvester API,只复用已有的 harvesterhci.io/v1beta1 Setting 资源,因此对现有 API 完全向后兼容。

对应的功能需求记录在 Harvester 仓库 issue #8581 中(此处不展开外部链接,仓库内源码即实现证据)。

二、核心使用场景:提升并行迁移数

设计文档给出了最典型的用户诉求——虚拟机较多时希望加快批量迁移速度。KubeVirt 的默认并行迁移数为 5,意味着同一时间最多只有 5 台虚拟机可以同时执行迁移。若集群规模较大、希望更快地排空节点,可通过修改 kubevirt-migration 设置的 parallelMigrationsPerCluster 字段,例如将其调大到 10:

{
  "parallelMigrationsPerCluster": 10
}

修改后,Harvester 会经由 Controller 链路把该配置同步到 KubeVirt 的 KubeVirt CR(对象位于 harvester-system 命名空间,名为 kubevirt),KubeVirt 随即按新参数调度迁移。

三、kubevirt-migration 设置的完整默认值

在源码 pkg/settings/settings.go 中,KubeVirtMigration 设置被定义并赋予如下默认 JSON:

{
  "parallelOutboundMigrationsPerNode": 2,
  "parallelMigrationsPerCluster": 5,
  "allowAutoConverge": false,
  "bandwidthPerMigration": 0,
  "completionTimeoutPerGiB": 150,
  "progressTimeout": 150,
  "unsafeMigrationOverride": false,
  "allowPostCopy": false,
  "allowWorkloadDisruption": false,
  "disableTLS": false,
  "matchSELinuxLevelOnMigration": false
}

字段含义与调优建议如下表(字段名与 KubeVirt MigrationConfiguration 一一对应):

字段 默认值 含义 调优建议
parallelOutboundMigrationsPerNode 2 每个节点同时允许进行的出站迁移数 节点资源充裕时可适当调大
parallelMigrationsPerCluster 5 整个集群同时允许进行的迁移总数 批量排空节点时建议调大(如 10、20)
allowAutoConverge false 是否允许迁移自动收敛(降低 vCPU 以追上内存脏页速率) 大内存、热数据 VM 迁移超时可开启
bandwidthPerMigration 0 单次迁移带宽上限(0 表示不限制) 若迁移网络带宽有限,可设置 Mbps 数值以限流
completionTimeoutPerGiB 150 每 GiB 内存允许的迁移完成超时(秒) 大内存 VM 建议调大
progressTimeout 150 迁移无进展超时(秒),超时则迁移失败 高负载网络下可调大
unsafeMigrationOverride false 是否允许在 unsafe 环境下强制执行迁移 一般不开启,可能引起数据不一致
allowPostCopy false 是否允许 Post-Copy 模式(先切换再拷贝剩余内存) 可显著缩短停机时间,但依赖网络持续可用
allowWorkloadDisruption false 是否允许迁移过程中短暂中断工作负载 保持默认 false 更安全
disableTLS false 迁移连接是否禁用 TLS 加密 生产环境保持 false
matchSELinuxLevelOnMigration false 迁移时是否匹配 SELinux 级别 启用 SELinux 的节点间迁移建议开启

用户既可整体覆盖该设置的 value,也可只修改部分字段(Harvester 的设置采用 JSON 合并语义,Controller 会将解析后的完整 MigrationConfiguration 写回 KubeVirt CR)。

四、Controller 同步链路:设置 → KubeVirt CR

4.1 同步函数的核心逻辑

kubevirt-migration 设置的同步器实现在 pkg/controller/master/setting/kubevirt_migration.go,核心流程如下:

  1. 取值优先级:若 setting.Value 非空则使用 Value,否则回退到 Default(第 16-20 行);
  2. JSON 解码:将设置字符串 json.Unmarshal 到 kubevirtv1.MigrationConfiguration 结构体(第 23-30 行),解码失败会返回错误并最终在 Setting 上体现为 configured=False 条件;
  3. 读取 KubeVirt CR:从 harvester-system/kubevirt(常量见 pkg/util/constants.go、pkg/util/constants.go)读取现有配置并 DeepCopy(第 32-37 行);
  4. 保护关键字段(第 41-45 行):
    • migrationConfiguration.NodeDrainTaintKey = nil——忽略设置中的该字段,注释明确说明默认值 kubevirt.io/drain 被升级脚本使用;
    • migrationConfiguration.Network = kubevirtCpy.Spec.Configuration.MigrationConfiguration.Network——用 KubeVirt CR 中现有的 network 覆盖设置中的 network,因为该字段由 vm-migration-network 设置负责管理;
  5. 仅在实际变化时更新:通过 reflect.DeepEqual 比较新配置与 CR 现有配置,一致则跳过,不一致才执行 kubeVirtConfig.Update(第 47-52 行),避免无谓的 CR 更新与事件风暴。

4.2 注册与变更触发机制

该同步器在 pkg/controller/master/setting/register.go 中注册到同步器映射表:

harvSettings.KubeVirtMigrationSettingName: controller.syncKubeVirtMigration,

设置变更的统一入口是 settings.OnChange(ctx, controllerName, controller.settingOnChanged)(见 register.go)。在 pkg/controller/master/setting/handler.go 中,settingOnChanged 会先计算设置值(连同 upgrade-patched 注解)的 SHA-256 哈希,并与上次成功同步后写入 AnnotationHash 注解的哈希比对:哈希未变化则直接跳过同步(第 122-124 行),从而保证"仅当设置真正变化时才更新 KubeVirt CR",与设计文档中的 "Update the KubeVirt CR only when the setting is changed" 完全一致。

4.3 同步结果反馈

同步成功或失败后,Controller 会更新 Setting 的状态条件 configured(定义于 pkg/apis/harvesterhci.io/v1beta1/settings.go,状态写入逻辑见 handler.go):成功且 Value 非空时置为 True,失败时置为 False 并记录错误消息。用户可在 UI 上据此判断本次修改是否已生效。

五、Webhook 校验:把住设置入口的"四道关卡"

为了防止用户误改关键字段或在迁移进行中造成混乱,Harvester 为 kubevirt-migration 设置了 Webhook 校验器。校验器在 pkg/webhook/resources/setting/validator.go 中注册:

validateSettingFuncs[settings.KubeVirtMigrationSettingName] = validator.validateKubeVirtMigration
validateSettingUpdateFuncs[settings.KubeVirtMigrationSettingName] = validator.validateUpdateKubeVirtMigration

validateUpdateKubeVirtMigration 直接委托给 validateKubeVirtMigration(validator.go),后者实现四道校验(validator.go):

  1. 进行中的迁移检查:通过 v.vmimCache.List(metav1.NamespaceAll, labels.Everything()) 列出全命名空间的 VirtualMachineInstanceMigration(VMI Migration),跳过处于删除中(DeletionTimestamp != nil)或已完成(Status.MigrationState.Completed)的对象;只要存在仍在进行的迁移,立即返回 BadRequest:"There is a VM Migration in progress, please wait until it is completed before updating the kubevirt-migration setting"。这保证了调参不会干扰正在进行的迁移;
  2. JSON 结构校验:分别对 Default 和 Value(两者均非空且非 {} 时)执行 settings.DecodeConfig<a href="https://link.gitcode.com/i/5d2db689678a74df72295a5bffc33d70" target="_blank">kubevirtv1.MigrationConfiguration](解码实现见 [pkg/settings/settings_helper.go),解码失败则返回 InvalidError,并分别指向 default / value 关键字,错误结构无法写入;
  3. nodeDrainTaintKey 保护:若设置中携带非空 NodeDrainTaintKey,返回 "nodeDrainTaintKey field cannot be configured"——该字段由升级脚本依赖,必须保持默认;
  4. network 保护:若设置中携带非空 Network,返回 "network field is configured by vm-migration-network setting"——迁移网络必须走 vm-migration-network 设置。

与 vm-migration-network 控制器的协同

network 字段的真正管理者是独立的 harvester-vm-migration-network-controller(pkg/controller/master/kubevirt/vm_migration_network.go)。该控制器监听 vm-migration-network 设置的变化,根据设置的 NAD(NetworkAttachmentDefinition)配置,在 harvester-system 命名空间自动创建 vm-migration-network-* 前缀的 NAD(第 174-207 行),并据此写入 KubeVirt CR 的 MigrationConfiguration.Network(第 137-140 行),同时用 SHA-1 哈希注解去重、清理旧 NAD。由此可见,两个设置各司其职:vm-migration-network 管"走哪条网络",kubevirt-migration 管"怎么迁(并发、带宽、超时)",Webhook 与 Controller 双层保证二者不会互相覆盖。

六、测试计划与验证要点

设计文档的 Test plan 小节明确了五条验收标准,结合上述源码可以逐一对应验证:

  1. 错误 schema 被拒绝:提交无法解码为 MigrationConfiguration 的 JSON,Webhook 返回 InvalidError(对应校验关卡 2);
  2. 修改 nodeDrainTaintKey 被拒绝:提交非空 nodeDrainTaintKey,Webhook 返回 "nodeDrainTaintKey field cannot be configured"(关卡 3);
  3. 修改 network 被拒绝:提交非空 network,Webhook 返回 "network field is configured by vm-migration-network setting"(关卡 4);
  4. 迁移进行中修改被拒绝:存在未完成且未删除的 VMI Migration 时,返回 "There is a VM Migration in progress..."(关卡 1);
  5. 合法且真实变更被接受:不满足以上拒绝条件,且设置值与上次同步哈希不同(Controller 侧 AnnotationHash 机制)时,修改被接受并同步到 KubeVirt CR。

需要说明的是,仓库的 tests/ 目录下目前未发现针对 kubevirt-migration 的独立测试文件(tests 目录 中的集成测试框架可在此基础上扩展),上述验收点以设计文档描述与 Webhook/Controller 源码实现为准。

七、配置约束小结与最佳实践

综合以上源码分析,使用 kubevirt-migration 设置时有以下注意事项:

  • 可修改字段:parallelMigrationsPerCluster、parallelOutboundMigrationsPerNode、bandwidthPerMigration、completionTimeoutPerGiB、progressTimeout、allowAutoConverge、allowPostCopy、unsafeMigrationOverride、allowWorkloadDisruption、disableTLS、matchSELinuxLevelOnMigration;
  • 不可修改字段:nodeDrainTaintKey(升级脚本依赖)、network(由 vm-migration-network 设置接管)——即使写入也会被 Webhook 拒绝或 Controller 忽略;
  • 修改时机:确保集群当前没有进行中的 VM 迁移,否则请求会被拒绝;
  • 生效范围:设置同步到 KubeVirt CR 后由 KubeVirt 统一生效,无需重启任何组件;Controller 通过哈希比对保证只在真实变更时更新,避免无谓的 API 调用;
  • 监控反馈:修改后可在 Harvester UI 查看 kubevirt-migration 设置的 configured 条件是否为 True,以此确认同步成功。

八、相关代码与文档索引

通过 kubevirt-migration 设置,Harvester 把 KubeVirt 迁移参数的调优门槛降到了 UI 层面,同时在 Webhook 与 Controller 双层防护下确保了升级脚本与迁移网络配置的稳定性——这正是"既要灵活可配、又要保护关键字段"这一设计权衡的完整落地。

登录后查看全文
harvester