Harvester项目：见证集群升级失败问题分析与解决方案

问题背景

在Harvester v1.4.0至v1.4.1-rc1版本的升级过程中，用户在使用见证(witness)集群时遇到了升级失败的问题。错误信息显示"admission webhook 'validator.harvesterhci.io' denied the request: managed chart harvester is not ready, please wait for it to be ready"。这一问题主要影响设置了默认存储类为副本数为2的见证集群环境。

问题现象

当用户尝试在以下环境中进行升级时会出现问题：

1. 全新安装的3节点见证集群
2. 创建了一个名为sc2、副本数为2的存储类，并将其设置为默认存储类
3. 准备并触发离线升级时失败

错误日志中显示，管理图表(ManagedChart) harvester-longhorn无法正确应用，因为系统检测到已存在默认存储类。

根本原因分析

经过深入调查，发现问题源于以下几个技术细节：

1. 存储类冲突：Harvester图表会自动设置harvester-longhorn存储类的storageclass.kubernetes.io/is-default-class: "true"属性。当用户手动设置其他存储类为默认时，系统在升级过程中会尝试重新应用这一设置，导致冲突。

2. 集群扩展机制：在集群构建过程中(如添加新节点时)，Harvester相关部署会自动扩展，这是由于management.cattle.io/scale-available注解的作用。这种自动扩展可能触发管理图表的重新部署。

3. 验证钩子限制：Harvester的验证webhook会阻止同时存在多个默认存储类的设置，这是Kubernetes的最佳实践要求，但在升级流程中造成了阻碍。

解决方案

开发团队提出了多层次的解决方案：

代码修复

1. 图表模板优化：在Harvester图表定义中添加条件判断，使用Helm的lookup功能检查是否已有其他存储类被标记为默认。

2. 控制器逻辑增强：当任何非harvester-longhorn存储类被设置为默认时，自动将管理图表中的spec.values.storageClass.defaultStorageClass字段设为false，避免冲突。

临时解决方案

对于受影响的用户，可以通过以下步骤临时解决问题：

1. 编辑harvester管理图表：

   kubectl edit managedchart -n fleet-local harvester
   

2. 将spec.values.storageClass.defaultStorageClass设置为false

3. 等待2分钟后，再将其设置为true

验证与测试

团队在多种场景下验证了修复方案的有效性：

1. 创建新存储类并设置为默认后，管理图表不再报错
2. 相同版本升级测试通过
3. 见证集群环境下的离线升级流程恢复正常

测试结果表明，修复方案不仅解决了原始问题，还提升了系统在存储类管理方面的健壮性。

技术实现细节

修复方案涉及以下几个关键技术点：

1. Helm模板条件判断：使用Helm的模板功能动态决定是否设置默认存储类标记，避免硬性覆盖用户设置。

2. 控制器协调逻辑：增强控制器对存储类状态变化的感知能力，自动调整管理图表配置。

3. 验证webhook优化：改进webhook的验证逻辑，提供更清晰的错误信息，同时保持Kubernetes的存储类管理规范。

最佳实践建议

基于此问题的解决经验，我们建议Harvester用户：

1. 在设置非默认存储类前，先检查系统默认存储类状态
2. 进行大规模配置变更前，备份关键资源定义
3. 遵循官方文档的升级指导，特别是在见证集群环境中
4. 监控管理图表状态，及时发现潜在配置冲突

总结

Harvester团队通过深入分析见证集群升级失败的根本原因，不仅解决了特定版本间的升级问题，还增强了系统在存储类管理方面的健壮性。这一问题的解决体现了Harvester项目对生产环境稳定性的重视，以及团队快速响应和解决复杂技术问题的能力。

对于使用见证集群架构的用户，建议关注后续版本更新，及时应用包含此修复的版本，以获得更稳定可靠的升级体验。