Kubespray 升级至 v1.31.1 常见问题解析

问题背景

在使用 Kubespray 从 v1.30.4 升级到 v1.31.1 版本时，许多用户遇到了升级过程中断的问题。典型错误表现为在执行 Kubeadm | Copy kubeadm patches from inventory files 任务时失败，错误信息提示循环处理的数据格式不正确。

错误原因分析

该问题的根本原因在于 Kubespray v1.31.1 对 kubeadm_patches 配置项的格式进行了重大变更。在之前的版本中，配置格式为：

kubeadm_patches:
  enabled: false
  source_dir: "{{ inventory_dir }}/patches"
  dest_dir: "{{ kube_config_dir }}/patches"

而在 v1.31.1 版本中，格式变更为更结构化的列表形式：

kubeadm_patches_dir: "{{ kube_config_dir }}/patches"
kubeadm_patches:
- target: kube-controller-manager
  type: merge
  patch:
   metadata:
     annotations:
       prometheus.io/scrape: "true"
       prometheus.io/port: "10257"

解决方案

针对此问题，用户需要采取以下步骤进行修复：

1. 修改 inventory 文件
   找到 inventory/<cluster_name>/group_vars/k8s_cluster/k8s-cluster.yml 文件，更新 kubeadm_patches 部分的配置。

2. 两种处理方式：

   • 不使用 patches 功能：直接设置为空列表

     kubeadm_patches_dir: "{{ kube_config_dir }}/patches"
     kubeadm_patches: []
     

   • 使用 patches 功能：按照新格式配置

     kubeadm_patches_dir: "{{ kube_config_dir }}/patches"
     kubeadm_patches:
     - target: kube-controller-manager
       type: merge
       patch:
        metadata:
          annotations:
            prometheus.io/scrape: "true"
            prometheus.io/port: "10257"
     

3. 升级注意事项：

   • 确保使用 upgrade-cluster.yml 而非 cluster.yml 进行升级
   • 升级前备份现有 inventory 配置
   • 升级后验证各节点版本是否一致

最佳实践建议

1. inventory 管理原则：

   • 避免直接复制 sample inventory 作为生产配置
   • 只保留必要的配置项，删除不需要的默认配置
   • 每次大版本升级前，仔细阅读 release notes 中的破坏性变更说明

2. 版本升级策略：

   • 在测试环境先验证升级流程
   • 分阶段升级集群节点（先控制平面，再工作节点）
   • 监控升级过程中的关键指标

总结

Kubespray 作为 Kubernetes 集群部署工具，随着版本迭代会不断优化配置结构。v1.31.1 版本对 kubeadm patches 配置的改进提供了更清晰、更灵活的配置方式。用户在升级时需要注意此类破坏性变更，按照新规范调整配置即可顺利完成升级。

对于生产环境，建议建立完善的配置管理流程，记录每次变更的配置项，这样在版本升级时可以快速定位和解决兼容性问题。同时，保持对 Kubespray 项目动态的关注，及时了解各版本的变更要点，是确保集群平稳升级的关键。