Kubespray 升级 Kubernetes 集群时 kubeadm_patches 配置变更指南

问题背景

在使用 Kubespray 进行 Kubernetes 集群升级时，从 v1.30.4 升级到 v1.31.1 版本过程中遇到了任务失败的情况。具体报错信息显示在 Kubeadm | Copy kubeadm patches from inventory files 任务阶段，系统提示 kubeadm_patches 变量格式不匹配。

问题原因分析

经过深入排查，发现这是由于 Kubespray 项目在近期版本中对 kubeadm_patches 配置格式进行了重大变更。旧版本中该配置采用字典结构，而新版本要求使用列表格式。

新旧配置格式对比

旧版本配置格式（v2.26.0及之前）

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

新版本配置格式（v2.27.0及之后）

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"
- target: kube-scheduler
  type: merge
  patch:
   metadata:
     annotations:
       prometheus.io/scrape: "true"
       prometheus.io/port: "10259"

解决方案

对于需要升级集群的用户，应采取以下步骤：

1. 备份现有配置：在进行任何修改前，先备份当前的 inventory 目录
2. 修改配置格式：
   • 将 kubeadm_patches 从字典格式改为列表格式
   • 或者如果不需要补丁功能，可以简单设置为空列表 kubeadm_patches: []
3. 移除旧补丁文件：删除 inventory 目录下的 patches 子目录（如果存在）
4. 重新运行升级：使用 upgrade-cluster.yml playbook 而非 cluster.yml

最佳实践建议

1. 避免复制样本配置：不要直接复制 sample 目录作为生产环境 inventory，只保留必要的自定义配置
2. 版本变更检查：在升级 Kubespray 版本时，仔细阅读 CHANGELOG 和 release notes
3. 测试环境验证：重要升级前先在测试环境验证配置变更
4. 模块化配置：将自定义配置与 Kubespray 默认配置分离，便于维护

技术细节说明

新的 kubeadm_patches 配置格式直接对应 Kubernetes 的 kubeadm 补丁机制，每个补丁包含三个关键属性：

1. target：指定要修补的组件（如 kube-apiserver、kube-controller-manager 等）
2. type：指定补丁类型（strategic、json 或 merge）
3. patch：实际要应用的补丁内容

这种格式变更使配置更加直观，且支持按顺序应用多个补丁，提供了更灵活的配置能力。

总结

Kubespray 作为 Kubernetes 集群部署工具，其配置格式会随着 Kubernetes 自身功能和最佳实践的发展而演进。用户在升级过程中遇到类似配置格式变更问题时，应首先查阅项目变更日志，理解新格式的设计意图，然后按照新规范调整配置。保持配置简洁并只包含必要项，是长期维护 Kubespray 部署的关键。