Kubespray 升级过程中外部 etcd 证书问题的分析与解决
问题背景
在使用 Kubespray 进行 Kubernetes 集群升级时(从 1.29.x 升级到 1.30.x),当集群采用外部 etcd 部署架构时,可能会遇到一个典型的证书路径错误。具体表现为升级过程中 kubeadm 尝试访问错误的证书文件路径,导致升级失败。
问题现象
升级任务在执行"Upgrade first master"步骤时失败,错误信息显示:
FATAL: failed to create etcd client for external etcd: open /etc/ssl/etcd/ssl/node-master03.pem
值得注意的是,当升级操作在 master01 节点上执行时,kubeadm 却尝试访问 master03 的证书文件,而该文件在 master01 节点上并不存在。
根本原因分析
经过深入调查,发现问题的根源在于 Kubernetes 集群配置中的不一致性:
-
配置映射(ConfigMap)问题:
kube-system
命名空间下的kubeadm-config
ConfigMap 中,etcd 外部连接配置错误地指向了集群中最后一个控制平面节点(如 master03)的证书,而非当前正在升级的节点证书。 -
证书分布问题:在外部 etcd 架构中,各 master 节点上只保留了自己的证书文件,而 ConfigMap 中的配置却要求所有节点都能访问同一个证书文件(最后一个节点的证书)。
-
kubeadm 行为变更:在较新版本的升级过程中,kubeadm 不再使用本地配置文件,而是直接从集群的 ConfigMap 中读取配置,这放大了配置不一致带来的问题。
解决方案
临时解决方案
对于已经出现此问题的集群,可以采取以下步骤进行修复:
- 检查并编辑
kubeadm-config
ConfigMap:
kubectl edit cm kubeadm-config -n kube-system
- 修改 etcd 外部连接配置部分,将其指向第一个控制平面节点(如 master01)的证书:
etcd:
external:
caFile: /etc/ssl/etcd/ssl/ca.pem
certFile: /etc/ssl/etcd/ssl/node-master01.pem
keyFile: /etc/ssl/etcd/ssl/node-master01-key.pem
-
确认所有 master 节点上都存在 master01 的证书文件(通常 Kubespray 部署时会自动复制这些文件)。
-
重新执行升级操作。
长期解决方案
对于使用 Kubespray 部署新集群或进行升级的用户,建议:
-
在升级前检查
kubeadm-config
ConfigMap 中的配置是否正确。 -
确保 Kubespray 版本是最新的,因为社区可能已经修复了相关配置生成逻辑。
-
对于外部 etcd 架构,考虑统一证书管理策略,确保必要的证书在所有相关节点上都可用。
技术细节深入
证书管理机制
在 Kubespray 部署的 Kubernetes 集群中,证书管理遵循以下原则:
-
内部 etcd:当 etcd 部署在控制平面节点上时,所有节点证书会被复制到所有 etcd 节点,因此不会出现证书找不到的问题。
-
外部 etcd:证书通常只部署在 etcd 节点和对应的控制平面节点上,导致当 ConfigMap 指向非本地节点证书时出现路径错误。
配置生成逻辑
Kubespray 在生成集群配置时:
-
使用 Jinja2 模板渲染
kubeadm-config.yaml
,其中 etcd 证书路径使用node-{{ inventory_hostname }}.pem
的变量形式。 -
在创建 ConfigMap 时,由于处理顺序的原因,可能会使用最后一个控制平面节点的 hostname 作为证书文件名。
最佳实践建议
-
升级前检查:在执行重要版本升级前,始终检查关键配置(如
kubeadm-config
ConfigMap)的一致性。 -
环境一致性:确保测试环境与生产环境的架构一致,提前发现潜在问题。
-
文档记录:维护集群配置变更记录,便于追踪问题根源。
-
监控配置:考虑实现对关键 ConfigMap 的监控,及时发现配置漂移。
总结
Kubespray 在外部 etcd 架构下的升级问题凸显了 Kubernetes 集群配置管理的重要性。通过理解证书管理机制和配置生成逻辑,管理员可以更好地预防和解决此类问题。随着 Kubespray 项目的持续发展,这类问题有望在后续版本中得到根本性解决。
HunyuanImage-3.0
HunyuanImage-3.0 统一多模态理解与生成,基于自回归框架,实现文本生成图像,性能媲美或超越领先闭源模型00ops-transformer
本项目是CANN提供的transformer类大模型算子库,实现网络在NPU上加速计算。C++045Hunyuan3D-Part
腾讯混元3D-Part00GitCode-文心大模型-智源研究院AI应用开发大赛
GitCode&文心大模型&智源研究院强强联合,发起的AI应用开发大赛;总奖池8W,单人最高可得价值3W奖励。快来参加吧~0289Hunyuan3D-Omni
腾讯混元3D-Omni:3D版ControlNet突破多模态控制,实现高精度3D资产生成00GOT-OCR-2.0-hf
阶跃星辰StepFun推出的GOT-OCR-2.0-hf是一款强大的多语言OCR开源模型,支持从普通文档到复杂场景的文字识别。它能精准处理表格、图表、数学公式、几何图形甚至乐谱等特殊内容,输出结果可通过第三方工具渲染成多种格式。模型支持1024×1024高分辨率输入,具备多页批量处理、动态分块识别和交互式区域选择等创新功能,用户可通过坐标或颜色指定识别区域。基于Apache 2.0协议开源,提供Hugging Face演示和完整代码,适用于学术研究到工业应用的广泛场景,为OCR领域带来突破性解决方案。00- HHowToCook程序员在家做饭方法指南。Programmer's guide about how to cook at home (Chinese only).Dockerfile09
- PpathwayPathway is an open framework for high-throughput and low-latency real-time data processing.Python00
项目优选









