Debian部署Kubernetes常见问题与解决方案
一 环境准备与内核网络
- 关闭 Swap：Kubernetes 要求关闭 Swap，否则 kubelet 预检失败。执行：sudo swapoff -a，并在 /etc/fstab 中注释包含 swap 的行，确保重启后仍然生效。
- 加载内核模块与开启转发：启用 overlay、br_netfilter 并设置桥接流量走 iptables，开启 IPv4 转发。示例：
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
sudo modprobe overlay && sudo modprobe br_netfilter
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF
sudo sysctl --system
- 防火墙与端口：确保节点间以下端口放通（示例以 UFW 为例）：
sudo ufw allow 6443/tcp
sudo ufw allow 2379/tcp,2380/tcp
sudo ufw allow 10250/tcp,10251/tcp,10252/tcp,10255/tcp
如未使用 UFW，请改用 iptables/nftables 或云安全组规则放行相同端口。
- 容器运行时选择：自 v1.20 起，Kubernetes 移除对 Docker 的直接支持，推荐使用 containerd 或 CRI-O；若必须使用 Docker，需通过 cri-dockerd 适配。
- 系统版本建议：优先选择 Debian 12，与主流 K8s 版本兼容性更好。
二 初始化与加入集群
- 安装 kubeadm/kubelet/kubectl：在所有节点安装相同版本组件，并标记为 hold 防止误升级：sudo apt install -y kubelet kubeadm kubectl && sudo apt-mark hold kubelet kubeadm kubectl。
- 初始化控制平面：示例（按需替换参数）：
sudo kubeadm init --pod-network-cidr 10.244.0.0/16
常见可追加参数：–apiserver-advertise-address、–control-plane-endpoint、–image-repository（如国内镜像源）、–service-cidr。
- 配置 kubectl：
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
- 工作节点加入：使用 kubeadm init 输出的 join 命令；若 Token 过期 或配置异常，在主节点重新生成后再加入：
kubeadm token create --print-join-command
- 验证：kubectl cluster-info、kubectl get nodes（状态应为 Ready）。
三 网络与 DNS 故障
- 网络插件未就绪：部署 Flannel/Calico 后若 Pod 间或节点间不通，先检查 DaemonSet 是否 Running：kubectl get pods -n kube-system -l app=flannel（或 calico）。异常时清理后重装：kubectl delete -f <plugin.yaml> 再 apply。
- Pod 网段与控制平面 Service 网段冲突：初始化时确保 –pod-network-cidr 与 –service-cidr 不重叠；常见组合为 pod 10.244.0.0/16、service 10.96.0.0/12。
- 内核转发与桥接参数未生效：若仍出现同节点 Service 不通或跨节点不通，复核 br_netfilter、ip_forward 是否加载并生效（见第一部分）。
- DNS 解析异常：确认 CoreDNS 运行正常：kubectl get pods -n kube-system -l k8s-app=coredns；若 CrashLoopBackOff，查看日志并核查上游 DNS、存活性探针与网络连通性。
四 镜像拉取与容器运行时
- ErrImagePull/ImagePullBackOff：
- 核对镜像名与标签是否正确；
- 使用国内镜像仓库或自建镜像仓库；
- 私有仓库需配置 /etc/docker/certs.d//ca.crt；
- 可手动 docker pull 并重新打 tag 验证。
- 使用 Docker 作为运行时的适配：Kubernetes v1.24+ 移除内置 dockershim，需部署 cri-dockerd 并在 kubeadm 配置中指定 criSocket（/var/run/cri-dockerd.sock）。
- 版本兼容：若 Docker 版本不在验证列表，优先选择与 K8s 兼容的版本，或调整 K8s 组件版本；升级时遵循官方兼容矩阵与升级策略。
五 节点与资源问题
- 节点 NotReady：常见原因为 kubelet 异常、容器运行时未就绪、网络插件未部署或内核参数缺失。按顺序排查：
- systemctl status kubelet；journalctl -u kubelet -xe
- crictl ps -a（或 docker ps）确认容器运行时可用
- kubectl describe node 查看 Conditions 与 Events
- 资源不足导致 Pod 被驱逐（Evicted）：检查磁盘与内存压力（kubectl describe node、节点监控），清理无用镜像/日志，必要时扩容节点或设置资源请求/限制。
- 权限与 kubeconfig：确保执行 kubectl 的用户拥有 /etc/kubernetes/admin.conf 读取权限，或正确设置 KUBECONFIG 环境变量；集群 RBAC 策略应授予所需权限。
- 服务访问异常：核查 Service 类型（ClusterIP/NodePort/LoadBalancer）、端口映射、外部负载均衡/Ingress 配置与证书有效性。