CentOS 安装 Kubernetes 的常见坑与规避
一 版本与内核兼容
- 在 CentOS 7.9 上，默认内核为 3.10，对高版本 K8s 的兼容性与网络性能影响较大：K8s 1.24+ 要求内核 ≥4.19；K8s 1.26+ 建议 ≥5.10；K8s 1.27+ 在 3.10 上可能出现功能或稳定性问题。实测在 CentOS 7.9 + K8s 1.31 上会出现网络“龟速”（千兆网卡仅 1–2 Mbps）等性能异常，升级到 Rocky Linux 9.6 + K8s 1.33.5 后恢复正常。建议：在 7.9 上优先选择 K8s 1.23.x；若需 1.24+，务必升级内核或直接迁移到 CentOS Stream 8 / Rocky Linux 8/9 / Ubuntu 22.04 等较新系统。
二 容器运行时与 kubeadm 版本匹配
- K8s 1.24 起移除内置的 Dockershim，默认使用 containerd。在 1.24+ 环境若仍用 Docker，需确保通过 cri-dockerd 适配，否则会出现类似 “CRI v1 runtime API is not implemented for endpoint …” 的错误。建议：1.23 及更早可用 Docker；1.24+ 使用 containerd（或 cri-dockerd），并保持 kubelet/kubeadm 版本一致。
三 镜像拉取与网络访问
- 初始化时若未指定镜像仓库，默认会从 k8s.gcr.io 拉取镜像，国内环境常失败；应使用国内镜像源，例如：kubeadm init 时加参数 –image-repository=registry.aliyuncs.com/google_containers。同时，部署 Flannel/Calico 等插件时，其清单中的境外镜像（如 quay.io/coreos/flannel 或 ghcr.io/flannel-io/flannel）在国内也常拉取失败，需提前在各节点手动拉取或替换镜像源。若访问 raw.githubusercontent.com 被拒，可在 /etc/hosts 中临时添加解析记录以完成清单下载。
四 系统前置条件与内核参数
- 常见被忽略的硬性要求：必须关闭 Swap（临时 swapoff -a 并注释 /etc/fstab）；按需关闭 firewalld 与 SELinux（生产环境请采用更细粒度策略）；加载内核模块 overlay、br_netfilter；配置 net.bridge.bridge-nf-call-iptables=1、net.bridge.bridge-nf-call-ip6tables=1、net.ipv4.ip_forward=1 并生效。内存过小（如 1GB）会导致 kubelet OOM 被 kill，建议至少 2–4GB。这些步骤缺失或不完整，节点极易卡在 NotReady 或组件反复 CrashLoopBackOff。
五 网络插件与 Pod CIDR 不匹配
- 部署 Flannel 时，清单中的 Network 字段必须与 kubeadm 初始化时的 –pod-network-cidr 一致，否则 Pod 跨节点通信异常。示例：Flannel 使用 10.244.0.0/16 时，kubeadm init 需指定 –pod-network-cidr=10.244.0.0/16。此外，插件版本要与 K8s 版本匹配，例如 K8s 1.20 应使用 Calico v3.20，而不是最新版 v3.23。错误的 CIDR 或不匹配的插件版本，常导致节点长时间 NotReady。
六 常见报错速查表
| 现象 |
可能原因 |
快速修复 |
| kubelet 启动失败或反复重启 |
内存不足（≤1GB） |
升级至 ≥2–4GB 内存 |
| kubeadm init 报 manifests 已存在 |
之前初始化残留 |
执行 kubeadm reset 后再 init |
| 节点 NotReady |
未装 CNI 或 Pod CIDR 不匹配 |
安装 Flannel/Calico 且确保 CIDR 一致 |
| 镜像拉取超时 |
境外仓库不可达 |
使用 –image-repository=registry.aliyuncs.com/google_containers 或预拉取镜像 |
| 清单下载失败 |
raw.githubusercontent.com 解析失败 |
在 /etc/hosts 添加临时解析 |
| 依赖安装失败（libnetfilter_queue 等） |
YUM 缓存或镜像源异常 |
执行 yum clean all && yum makecache 后重试 |
| “CRI v1 runtime API is not implemented …” |
1.24+ 仍用 Docker 且未适配 |
改用 containerd 或部署 cri-dockerd |
以上要点覆盖了版本/内核、运行时、镜像、系统配置、网络插件与常见报错六个维度，按此清单核对，能避开绝大多数“装不上/起不来/网络不通”的问题。
