Debian与Kubernetes安装兼容性要点与避坑清单
一 兼容性与版本选择
- 操作系统建议优先选用Debian 12，对主流Kubernetes版本支持更完善；Debian 11仍可部署，但部分新版本Kubernetes在依赖与内核特性上更偏向Debian 12，出现问题的概率更高。
- 容器运行时从Kubernetes 1.24起移除内置的dockershim，如需使用 Docker，需额外配置cri-dockerd；更推荐直接使用containerd以避免兼容性与维护负担。
- 基础硬件建议：至少2核CPU、2GB内存（推荐4GB+）、20GB+磁盘，并确保节点间网络互通。
二 常见兼容性问题与对策
- Swap未关闭：Kubelet要求关闭Swap，否则节点可能NotReady。执行：sudo swapoff -a 并注释/etc/fstab中的swap行。
- iptables/nftables兼容：部分网络插件在nftables环境下异常，建议切换为iptables-legacy：sudo update-alternatives --config iptables。
- 防火墙/端口未放行：确保节点间开放6443、2379、2380等关键端口，或临时关闭防火墙用于排查。
- 内核/系统参数未调优：如未设置桥接流量转发，Pod间可能不通；需开启net.bridge.bridge-nf-call-iptables等。
- 容器运行时不匹配：K8s 1.24+未配置cri-dockerd而直接使用Docker会失败；或containerd未正确启用镜像与运行时。
- 版本不匹配：kubelet/kubeadm/kubectl与集群版本差异过大，易导致初始化或升级失败；建议保持三者版本一致并遵循官方版本矩阵。
- 网络插件与Pod CIDR不匹配：如Flannel默认使用10.244.0.0/16，与kubeadm init的–pod-network-cidr不一致会导致Pod网络异常。
三 安装与配置建议
- 容器运行时优先选择containerd（简化维护、与K8s集成更稳）；若必须使用Docker，安装cri-dockerd并配置kubelet使用cri-dockerd.sock。
- 添加Kubernetes APT源并安装组件：curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -；echo “deb https://apt.kubernetes.io/ kubernetes-xenial main” | sudo tee /etc/apt/sources.list.d/kubernetes.list；sudo apt-get update && sudo apt-get install -y kubelet kubeadm kubectl；sudo apt-mark hold kubelet kubeadm kubectl。
- 初始化与网络：kubeadm init --pod-network-cidr=10.244.0.0/16；完成后安装Flannel：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml；最后配置kubectl并验证：mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config；kubectl cluster-info && kubectl get nodes。
四 快速排查路径
- 查看节点与系统状态：kubectl get nodes；kubectl describe node ；检查kubelet与容器运行时服务是否Active。
- 查看日志定位组件故障：journalctl -u kubelet -xe；如用containerd，journalctl -u containerd；必要时查看kube-apiserver、kube-controller-manager等容器日志。
- 网络连通性：在节点上验证Pod网段路由、跨节点端口连通性；检查CNI插件Pod是否Running。
- 资源与配置：确认CPU/内存充足；核对kubelet启动参数、容器运行时Endpoint、镜像仓库可达性。