Kubernetes kOps项目升级v1.26时ServiceAccountIssuer变更问题解析

在Kubernetes集群管理工具kOps从v1.25升级到v1.26版本的过程中，一个关键变化是移除了masterInternalName配置项。这个看似简单的变更实际上会引发一系列连锁反应，特别是对ServiceAccount令牌签发机制的影响，可能导致集群升级后关键组件如Calico网络插件无法正常工作。

问题背景

当用户尝试将kOps从v1.25.4升级到v1.26.6版本时，升级过程中会自动修改两个关键配置：

1. 移除显式指定的masterInternalName
2. 自动将serviceAccountIssuer和serviceAccountJWKSURI的值从原来的master.cluster.domain变更为api.internal.cluster.domain

这种变更导致的核心问题是：所有依赖ServiceAccount令牌进行认证的组件（如Calico CNI插件）会突然无法通过认证，因为它们持有的令牌是由旧的签发者(master.cluster.domain)签发的，而API Server现在只认可新签发者(api.internal.cluster.domain)的令牌。

问题表现

升级过程中最明显的症状是：

1. Calico-node Pod中的install-cni init容器启动失败，报错"Unable to create token for CNI kubeconfig error=Unauthorized"
2. 其他依赖k8s API的Pod也出现类似的未授权错误
3. 新启动的控制平面节点上的核心组件无法正常工作

根本原因分析

这个问题源于Kubernetes的服务账户令牌签发机制。在Kubernetes中：

1. ServiceAccount令牌包含签发者(issuer)信息
2. API Server会验证请求中令牌的签发者是否与当前配置的serviceAccountIssuer匹配
3. 当签发者变更时，所有现有的令牌立即失效
4. kOps v1.26强制使用api.internal.cluster.domain作为签发者，不再支持自定义的masterInternalName

解决方案

经过实践验证，可以采用以下分阶段迁移方案来平滑过渡：

第一阶段：准备阶段

1. 在集群配置中添加additionalSans，包含原masterInternalName的值
2. 从集群配置中移除masterInternalName
3. 在master节点组中添加pre-hook，临时修改kube-apiserver manifest，将原签发者作为主签发者

第二阶段：初始迁移

4. 应用配置变更并滚动更新master节点
5. 手动创建master.cluster.domain的DNS记录指向master节点IP
6. 更新kubernetes-services-endpoint ConfigMap中的KUBERNETES_SERVICE_HOST值（如使用Calico CNI）

第三阶段：签发者切换

7. 更新pre-hook，将新签发者设为主签发者，原签发者作为辅助签发者
8. 再次应用变更并滚动更新master节点
9. 滚动更新集群中所有worker节点

第四阶段：清理阶段

10. 等待24小时确保所有动态SA令牌刷新
11. 移除master节点组中的pre-hook
12. 从集群配置中移除additionalSans
13. 最后滚动更新master节点
14. 删除临时的master.cluster.domain DNS记录

技术要点

在整个迁移过程中，有几个关键点需要特别注意：

1. DNS记录的维护至关重要 - 必须确保master.cluster.domain始终正确解析到当前master节点的IP
2. 分阶段切换签发者可以避免服务中断 - 先添加新签发者为辅助，再提升为主签发者
3. 足够的等待时间 - 确保所有组件都有机会刷新它们的ServiceAccount令牌
4. 全节点滚动更新 - 确保集群中所有节点都使用新配置

未来改进

kOps社区已经意识到这个问题，并在新版本中计划添加对多ServiceAccount签发者的原生支持。这将使类似的迁移变得更加简单和安全，无需复杂的pre-hook操作。

对于计划升级到kOps v1.26及更高版本的用户，建议：

1. 提前规划ServiceAccount签发者迁移策略
2. 在测试环境验证迁移方案
3. 考虑等待支持多签发者的kOps版本发布后再进行升级

通过这种谨慎的迁移方法，用户可以确保集群在kOps升级过程中保持稳定，避免因ServiceAccount令牌失效导致的服务中断。