Debian上Kubernetes部署的常见误区与规避
一 系统准备与内核参数
- 未关闭或未永久禁用 Swap：Kubelet 默认不支持 Swap，未关闭会导致节点 NotReady 或 kubelet 反复重启。应在所有节点执行：
swapoff -a 并注释 /etc/fstab 中的 swap 行。
- 未加载必需内核模块或未设置关键 sysctl：缺少 br_netfilter、overlay 或未启用
net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1，会造成 Pod 间网络不通、Service 解析异常。建议将模块写入 /etc/modules-load.d/containerd.conf，将 sysctl 写入 /etc/sysctl.d/99-kubernetes-k8s.conf 并执行 sysctl --system。
- 防火墙/安全组未放行关键端口：如 6443（API Server）、10250（kubelet）、以及 Calico/Flannel 所需端口，导致节点无法加入或组件异常。应在 UFW/iptables 或云安全组放行对应端口。
- 主机名与 /etc/hosts 未正确配置：节点间解析失败会影响 kubelet 注册与控制面通信。应为每个节点设置唯一 hostname 并在 /etc/hosts 中写入 “IP 主机名” 映射。
二 容器运行时与镜像
- 运行时选择或配置不当：未安装或未正确配置 containerd（或 Docker 的 cri-dockerd 适配），会导致 kubeadm init 超时、组件容器起不来。需安装运行时、启用模块与 sysctl，并确认 kubelet 使用正确的 CRI endpoint。
- 镜像拉取失败：国内环境直连 registry.k8s.io 常超时。可用
kubeadm config images list 查看所需镜像，提前从国内镜像仓库拉取并重命名，或配置镜像仓库镜像。
- 未将 kubelet、kubeadm、kubectl 设为 hold：系统升级可能替换组件版本，引发版本不匹配。安装后执行
apt-mark hold kubelet kubeadm kubectl。
三 网络与 Service 暴露
- 未安装或未正确部署 CNI 网络插件：集群会停留在 NotReady。应在控制面就绪后尽快部署 Calico/Flannel 等插件，并确认 Pod 网段与控制面配置一致。
- iptables 与 nftables 兼容性问题：部分网络插件在 nftables 环境下异常。可通过
update-alternatives --config iptables 选择 iptables-legacy 以提升兼容性。
- Service 类型误用：将服务类型设为 ClusterIP 却期望外网访问，导致访问被拒绝。应根据场景选择 NodePort/LoadBalancer，或使用 Ingress。
- 端口映射与资源定义错误：Service 端口冲突或 Pod resources.limits 未设置，易出现连接被拒绝、Pod 被 OOM 终止等问题。部署前检查 Service 定义与资源配额。
四 初始化、加入与权限
- kubeadm init 超时或失败：常见原因为 kubelet 未运行、cgroups 被禁用、或控制面镜像未就绪。应依次排查：
systemctl status kubelet、journalctl -xeu kubelet，并用 crictl 查看容器日志定位失败组件。
- 加入命令过期或 token/ca-cert-hash 错误：节点报 “Unauthorized” 或无法加入。需在控制面重新生成 join 命令（含新 token 与 hash），并在有效期内执行。
- kubeconfig 未正确配置：普通用户无法执行
kubectl。应将 /etc/kubernetes/admin.conf 复制到 $HOME/.kube/config 并修正属主。
- 证书与 HTTPS 验证问题：访问 API 或镜像仓库出现证书不受信任，需更新 CA 证书或在调试阶段谨慎使用
-k/--insecure（生产环境不建议）。
五 排错与验证清单
- 快速自检流程：
kubectl get nodes 与 kubectl get pods -A 查看节点与系统 Pod 状态；systemctl status kubelet 与 journalctl -xeu kubelet 定位组件异常；crictl ps -a | grep kube 与 crictl logs <id> 查看控制面临时容器日志；- 复核 6443/10250 等端口连通性与防火墙规则；
- 确认 CNI 已部署且 Pod 网段配置正确。
- 常见症状与定位要点：
- 节点 NotReady：优先检查 CNI、内核模块与 sysctl、节点间网络连通性；
- Pod CrashLoopBackOff/ErrImagePull：检查镜像名称、仓库可达性与拉取密钥；
- 外网访问失败：核对 Service type 与 NodePort/Ingress 配置；
- 节点无法加入：确认 join 命令、token 有效期与 CA hash。
