Harvester KubeVirt 迁移设置(kubevirt-migration)全解析:UI 配置、Webhook 校验与控制器同步机制
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 小节)非常明确:
- 将 KubeVirt 迁移配置暴露为 Harvester 的
kubevirt-migration设置,用户可在 Harvester UI 上直接查看与修改; - 不得破坏升级脚本:升级脚本依赖
nodeDrainTaintKey,因此该字段不允许用户修改; - 不得覆盖网络配置:迁移网络(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,核心流程如下:
- 取值优先级:若
setting.Value非空则使用Value,否则回退到Default(第 16-20 行); - JSON 解码:将设置字符串
json.Unmarshal到kubevirtv1.MigrationConfiguration结构体(第 23-30 行),解码失败会返回错误并最终在Setting上体现为configured=False条件; - 读取 KubeVirt CR:从
harvester-system/kubevirt(常量见 pkg/util/constants.go、pkg/util/constants.go)读取现有配置并DeepCopy(第 32-37 行); - 保护关键字段(第 41-45 行):
migrationConfiguration.NodeDrainTaintKey = nil——忽略设置中的该字段,注释明确说明默认值kubevirt.io/drain被升级脚本使用;migrationConfiguration.Network = kubevirtCpy.Spec.Configuration.MigrationConfiguration.Network——用 KubeVirt CR 中现有的network覆盖设置中的network,因为该字段由vm-migration-network设置负责管理;
- 仅在实际变化时更新:通过
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):
- 进行中的迁移检查:通过
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"。这保证了调参不会干扰正在进行的迁移; - 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关键字,错误结构无法写入; nodeDrainTaintKey保护:若设置中携带非空NodeDrainTaintKey,返回"nodeDrainTaintKey field cannot be configured"——该字段由升级脚本依赖,必须保持默认;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 小节明确了五条验收标准,结合上述源码可以逐一对应验证:
- 错误 schema 被拒绝:提交无法解码为
MigrationConfiguration的 JSON,Webhook 返回 InvalidError(对应校验关卡 2); - 修改
nodeDrainTaintKey被拒绝:提交非空nodeDrainTaintKey,Webhook 返回"nodeDrainTaintKey field cannot be configured"(关卡 3); - 修改
network被拒绝:提交非空network,Webhook 返回"network field is configured by vm-migration-network setting"(关卡 4); - 迁移进行中修改被拒绝:存在未完成且未删除的 VMI Migration 时,返回
"There is a VM Migration in progress..."(关卡 1); - 合法且真实变更被接受:不满足以上拒绝条件,且设置值与上次同步哈希不同(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,以此确认同步成功。
八、相关代码与文档索引
- 设计文档:enhancements/20250922-kubevirt-migration-setting.md
- 设置定义与默认值:pkg/settings/settings.go、pkg/settings/settings.go
- Controller 同步器:pkg/controller/master/setting/kubevirt_migration.go
- 同步器注册:pkg/controller/master/setting/register.go
- 设置变更统一入口与哈希机制:pkg/controller/master/setting/handler.go
- Webhook 校验器:pkg/webhook/resources/setting/validator.go
vm-migration-network控制器:pkg/controller/master/kubevirt/vm_migration_network.go- 设置状态条件定义:pkg/apis/harvesterhci.io/v1beta1/settings.go
- 相关增强文档:enhancements/20250519-vm-migration-network.md、enhancements/20220726-vm-migration.md
通过 kubevirt-migration 设置,Harvester 把 KubeVirt 迁移参数的调优门槛降到了 UI 层面,同时在 Webhook 与 Controller 双层防护下确保了升级脚本与迁移网络配置的稳定性——这正是"既要灵活可配、又要保护关键字段"这一设计权衡的完整落地。