CentOS 部署 Kubernetes 的坑与规避清单
一 版本与组件兼容
- 内核与系统版本：在 CentOS 7.9（内核 3.10） 上，建议最高选择 Kubernetes 1.23.x；从 v1.24 起对内核要求提升到 ≥4.19，在 v1.26+ 建议 ≥5.10，否则容易出现网络、eBPF、io_uring 等特性不兼容或稳定性问题。若必须使用 v1.24+，优先考虑升级内核或使用 CentOS Stream 8/9。
- 运行时选择：v1.24 起移除 dockershim，默认使用 containerd；若坚持用 Docker，需要额外安装 cri-dockerd 并配置 CRI 套接字，复杂度与维护成本上升。
- 组件版本对齐：控制平面组件版本应一致（如 kubeadm/kubelet/kube-apiserver 同版本），节点上的 kubelet 一般允许与控制平面相差不超过 1 个次版本，kubectl 允许 ±1 个次版本；跨大版本混用容易触发预检失败或运行时异常。
- 网络插件版本匹配：插件与 K8s 版本强相关，例如 Calico v3.23 不再支持 K8s v1.20，对应版本应取 v3.20；部署前务必核对插件兼容矩阵。
二 系统与安全基线
- 必须项：禁用 Swap（
swapoff -a 并注释 /etc/fstab）、加载内核模块 overlay/br_netfilter、开启 net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1，否则 Pod 网络、跨主机通信、kube-proxy 等都会异常。
- 防火墙与 SELinux：实验/学习环境常直接关闭 firewalld 与 SELinux 以简化排障；生产环境应改为精细化放行（如 6443/10250/8472/30000-32767 等端口与 CNI 所需规则），避免“一刀切”带来安全风险。
- 资源与稳定性：低于 2GB 内存 的节点极易 OOM 导致 kubelet 被杀；建议至少 2 核 CPU / 2GB 内存 / 30GB 磁盘，更稳妥为 4 核 / 4GB+。
三 容器运行时与镜像
- containerd 配置要点：启用 SystemdCgroup = true，设置 sandbox_image（如国内镜像 registry.aliyuncs.com/google_containers/pause:3.9），并配置 registry.mirrors 以加速拉取；错误的 cgroup 驱动或镜像源会直接导致 Pod 启动失败。
- 镜像拉取失败：常见为 ErrImagePull/ImagePullBackOff，需核对镜像名与标签、镜像仓库可达性、网络与代理；国内环境建议配置镜像加速或预先拉取所需镜像。
- 证书问题：访问 API 或组件间通信出现 证书验证失败，应更新/替换证书，或在调试阶段谨慎使用
--cacert/--insecure（生产禁用）。
四 网络与 CNI 插件
- Pod 网段与 Service 网段：初始化时指定的 –pod-network-cidr 必须与所用 CNI 配置一致；例如 Flannel 默认使用 10.244.0.0/16，若自定义需同步修改
kube-flannel.yml 中的 Network 字段。
- 节点 NotReady：多数因 CNI 未就绪/镜像拉取失败/配置不匹配；先检查
kube-flannel 或 calico 的 DaemonSet 是否 Running，再核对镜像、网段与后端（如 vxlan）。
- 虚拟机与云环境：在虚拟化/云主机上，确保网卡开启 Promiscuous 模式（或对应云厂商的混杂/开启 MAC 欺骗），否则 VXLAN 封装流量可能被丢弃。
- 外网访问：服务仅在集群内可达通常是 Service 类型不当（如仅 ClusterIP）；需改为 NodePort/LoadBalancer，并配合云厂商 LB 或 Ingress Controller。
五 初始化与运维细节
- 避免重复初始化：若
/etc/kubernetes/manifests/*.yaml 已存在或 10250 端口被占用，kubeadm init 会报预检错误；应先清理（kubeadm reset）或排查占用进程后再初始化。
- 保存 Join 命令：初始化成功后务必保存
kubeadm join ... 命令；若遗失，可用 kubeadm token create --print-join-command 重新生成（注意 v1.24+ 需手动管理 token）。
- 时间与 DNS：节点时间不同步会影响 证书校验、调度与组件通信；建议安装 ntp/chrony 并统一时区。
- 日志与排障：优先查看 kubelet、containerd、CNI 的日志（
journalctl -u kubelet -f、crictl logs <pod>），配合 kubectl describe pod <pod> 与 kubectl get events -A 快速定位镜像、网络、权限等问题。
