Ubuntu 与 Kubernetes 兼容性问题的系统解决路径
一 版本矩阵与前置检查
- 明确三点：你的 Ubuntu 版本、选择的 Kubernetes 版本、使用的 容器运行时（如 containerd 或 Docker 通过 cri-dockerd）。
- 运行以下命令收集关键信息：
- lsb_release -a 或 cat /etc/os-release（查看 Ubuntu 版本/代号）
- kubeadm version、kubelet --version（查看 K8s 版本）
- sudo crictl version 或 sudo docker version（查看 运行时）
- sudo systemctl is-active containerd docker（确认 运行时服务状态）
- 对照官方支持矩阵与发行说明，确保三者组合在支持范围内；若使用云厂商托管集群（如 AKS），还需满足其 OS SKU 与 K8s 版本的绑定关系（例如 Ubuntu 与 K8s 的受支持区间、默认 OS 变化等），避免“OS 过新/过旧”导致不兼容。
二 常见兼容性问题与修复清单
- 仓库地址或 GPG 密钥错误（典型报错：仓库 “https://apt.kubernetes.io kubernetes-xenial Release” 没有 Release 文件）
- 原因：旧版仓库路径含 xenial/jammy 等代号，已不再维护；新版仓库为通用路径，不再依赖 Ubuntu 代号。
- 修复：
- 删除旧源：sudo rm /etc/apt/sources.list.d/kubernetes.list
- 添加新源（示例为 v1.28 系列）：
echo “deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /” | sudo tee /etc/apt/sources.list.d/kubernetes.list
- 导入 GPG：curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-archive-keyring.gpg
- 更新并安装：sudo apt update && sudo apt install -y kubeadm=1.28.* kubelet=1.28.* kubectl=1.28.*
- 验证：cat /etc/apt/sources.list.d/kubernetes.list 应显示通用路径；必要时 curl -I 检测仓库可达性。
- 运行时与 K8s 版本不匹配（如 K8s ≥1.24 移除 dockershim，仍用 Docker 直连会失败）
- 现象：kubelet 日志出现 “CRI v1 runtime API is not implemented …” 或 “connection refused”。
- 修复：
- 方案 A（推荐）：使用 containerd 作为运行时（配置 SystemdCgroup、重启 containerd 与 kubelet）。
- 方案 B：保留 Docker 时，安装 cri-dockerd 并配置 kubelet 使用其 endpoint。
- 方案 C：若必须使用老版本 Docker 与老版 K8s，可将 K8s 降至 1.23.x 等仍包含 dockershim 的版本（仅建议过渡）。
- 节点无法加入或长期 NotReady（AKS 常见）
- 现象：节点加入命令过期、kubelet 参数过低导致 API 限流、节点镜像过旧。
- 修复：
- 重新生成加入命令：kubeadm token create --print-join-command
- 适度提升 kubelet 参数（示例）：–kube-api-qps=20、–kube-api-burst=30；必要时设置 --kube-reserved、–system-reserved 并重启 kubelet。
- 升级节点池镜像/OS 版本（AKS CLI）：az aks nodepool upgrade --resource-group --cluster-name --name --node-image-only --kubernetes-version --os-sku Ubuntu2204。
- 容器长期 Terminating（镜像/内核/信号问题）
- 现象：Pod 删除后卡在 Terminating，只能 --grace-period=0 --force 强制删除。
- 修复：更换基础镜像（如从 eclipse-temurin:11-jdk 改为 Alpine 或其他基础镜像）验证是否为镜像/glibc/信号交互问题；同时检查业务进程对 SIGTERM 的处理逻辑。
- 云平台 OS SKU 与特性限制（以 AKS 为例）
- 例如：Ubuntu 24.04 在 K8s 1.32–1.38 支持但处于预览；启用 CVM 时 Ubuntu 22.04 不支持、需 Ubuntu 24.04；迁移 OS SKU 有时需要新建节点池而非就地升级。以上限制需在规划阶段确认。
三 标准化修复流程
- 步骤 1 基线检查：记录 Ubuntu 版本/内核、K8s 版本、运行时与关键服务状态。
- 步骤 2 对齐版本：按支持矩阵选择兼容的 K8s 与运行时组合；云上场景同步确认 OS SKU 支持范围。
- 步骤 3 修复仓库与密钥：清理旧源，使用 pkgs.k8s.io 新仓库与 GPG，执行 apt update。
- 步骤 4 配置运行时：优先 containerd（配置 SystemdCgroup），或安装 cri-dockerd 兼容 Docker。
- 步骤 5 启动与自举：启动 containerd/kubelet，执行 kubeadm init/join，安装 CNI 网络插件。
- 步骤 6 验证：kubectl get nodes -o wide、kubectl get pods -A；检查 kubelet 与容器运行时日志无异常。
- 步骤 7 回归测试：滚动升级一个小应用，验证 Terminating/调度/镜像拉取等场景正常。
四 云厂商与托管集群注意事项
- AKS 场景：
- Ubuntu 24.04 作为 K8s 1.34–1.38 的默认 OS；1.32–1.38 支持 Ubuntu 24.04（预览阶段有功能限制，如 FIPS 不支持）。
- CVM（机密 VM） 仅在 Ubuntu 24.04 且 K8s 1.32–1.38 支持；迁移到 CVM 通常需新建节点池（不可就地变更）。
- 若需从旧 OS 升级，优先采用“新建节点池 + 迁移工作负载”的方式，降低风险。
五 最小化复现与验证脚本
- 快速检查脚本（在节点上执行）：
- OS：lsb_release -a
- K8s：kubeadm version && kubelet --version
- 运行时：sudo crictl version || sudo docker version
- 服务：sudo systemctl is-active containerd && sudo systemctl is-active docker
- 仓库：cat /etc/apt/sources.list.d/kubernetes.list | head -n1
- 网络：ping -c 4 pkgs.k8s.io && curl -I https://pkgs.k8s.io/core:/stable:/v1.28/deb/
- 日志：sudo journalctl -u kubelet -n 200 --no-pager | tail -n 50
- 一键修复仓库与安装示例（适配 Ubuntu 20.04/22.04/24.04，K8s 1.28.x）：
- sudo rm -f /etc/apt/sources.list.d/kubernetes.list
- echo “deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /” | sudo tee /etc/apt/sources.list.d/kubernetes.list
- curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-archive-keyring.gpg
- sudo apt update && sudo apt install -y kubeadm=1.28.* kubelet=1.28.* kubectl=1.28.*
- sudo systemctl enable --now kubelet
- 提示：生产环境请固定 K8s 小版本（如 1.28.x），并在变更窗口内执行，配合回滚预案与监控告警。
