K8S部署在Debian上的故障排除

K8S部署在Debian上的常见故障及排除步骤

1. 系统基础环境问题

• 现象：节点无法正常启动Kubernetes组件、Pod调度失败或网络不通。
• 排查要点：
  • 硬件要求：确保节点满足Kubernetes最低配置（≥2核CPU、≥2GB内存、≥20GB磁盘空间）；
  • 系统更新：运行sudo apt update && sudo apt upgrade -y更新系统，避免软件包冲突；
  • 内核参数：加载必要模块（sudo modprobe overlay && sudo modprobe br_netfilter），并通过sysctl设置net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1（需写入/etc/sysctl.d/99-kubernetes.conf并执行sysctl -p生效）；
  • 关闭Swap：运行sudo swapoff -a临时关闭，修改/etc/fstab永久禁用（注释含swap的行）。

2. Kubelet服务异常

• 现象：kubelet服务无法启动、状态显示inactive (dead)或日志报错（如failed to start container runtime）。
• 排查步骤：
  • 检查服务状态：systemctl status kubelet（查看是否运行及错误信息）；
  • 查看详细日志：journalctl -u kubelet -f（跟踪实时日志，定位具体错误，如镜像拉取失败、证书问题）；
  • 重启服务：systemctl restart kubelet（修复临时故障）。

3. 节点无法注册到Master

• 现象：Worker节点执行kubeadm join时报错（如token expired、无法获取ConfigMap、connection refused）。
• 解决方法：
  • 重新生成Token：在Master节点运行kubeadm token create --print-join-command，获取新的join命令；
  • 验证Master状态：确保Master节点kubectl get nodes显示Ready，且kube-apiserver服务正常（systemctl status kube-apiserver）；
  • 检查网络连通性：Worker节点能ping通Master节点的IP（尤其是6443端口，用于API Server通信）。

4. Pod状态异常

• ErrImagePull（无法拉取镜像）：
  • 原因：镜像名称/标签错误、镜像不存在于仓库、私有仓库未配置证书。
  • 解决：检查Pod YAML中的image字段（如nginx:latest是否正确）；若使用私有仓库，在Worker节点的/etc/docker/certs.d/<registry-domain>/目录下添加证书，并重启Docker（systemctl restart docker）。
• CrashLoopBackOff（容器反复崩溃）：
  • 原因：应用启动失败（如端口冲突、依赖缺失）、资源不足（内存/CPU超出限制）。
  • 解决：查看Pod日志（kubectl logs <pod-name> -n <namespace>），检查应用错误；调整资源请求/限制（resources.requests和resources.limits）。

5. 网络插件问题

• 现象：Pod之间无法通信、Service无法访问（如ClusterIP无法内网访问、NodePort无法外网访问）。
• 排查步骤：
  • 确认插件部署状态：kubectl get pods -n kube-system（检查Flannel、Calico等插件Pod是否Running）；
  • 重新部署插件：删除现有插件配置（如kubectl delete -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml），再重新应用；
  • 检查内核模块：确保br_netfilter已加载（lsmod | grep br_netfilter）；
  • 验证网络参数：sysctl net.bridge.bridge-nf-call-iptables（需为1）。

6. 服务访问失败

• 现象：kubectl get svc显示服务端口正常，但无法通过NodeIP:NodePort或ClusterIP访问。
• 原因及解决：
  • 服务类型错误：ClusterIP仅集群内部可访问，需改为NodePort（type: NodePort）或LoadBalancer（需云厂商支持）；
  • 端口映射错误：检查Service YAML中的ports字段（如targetPort需与应用容器端口一致，port为Service端口，nodePort为可选的外部访问端口（30000-32767））；
  • 防火墙拦截：开放NodePort端口（sudo ufw allow <node-port>）。

7. 证书问题

• 现象：kubectl命令报错（如x509: certificate signed by unknown authority）、无法访问API Server。
• 解决方法：
  • 更新证书：若证书过期，在Master节点运行kubeadm certs renew all，然后重启相关组件（systemctl restart kubelet）；
  • 临时禁用验证（仅测试环境）：使用kubectl --insecure-skip-tls-verify=true命令，或修改~/.kube/config中的insecure-skip-tls-verify为true（不推荐生产环境）。

8. 资源不足

• 现象：Pod状态为Pending（无法调度）、系统频繁触发OOM Killer（杀死进程释放内存）。
• 排查与解决：
  • 查看资源使用：kubectl describe node <node-name>（查看节点资源分配情况）；kubectl top pod（查看Pod资源占用）；
  • 清理磁盘空间：删除无用文件（如/var/log/下的旧日志），或扩展磁盘容量；
  • 调整资源请求：修改Pod YAML中的resources.requests（如memory: "512Mi"、cpu: "500m"），避免过度申请资源。

9. 内核模块缺失

• 现象：kubelet日志报错（如sysctl: cannot stat /proc/sys/net/bridge/bridge-nf-call-iptables）、网络插件无法正常工作。
• 解决步骤：
  • 加载模块：sudo modprobe br_netfilter && sudo modprobe overlay；
  • 永久生效：将模块名添加到/etc/modules-load.d/kubernetes.conf文件中（每行一个模块），然后运行sudo systemctl restart systemd-modules-load。

10. 版本兼容性问题

• 现象：kubeadm init或kubeadm join时报错（如unsupported Docker version、kubelet版本与kube-apiserver不兼容）。
• 解决方法：
  • 检查兼容性：参考Kubernetes官方文档的《Compatibility Matrix》，确保Docker、kubelet、kube-apiserver等组件版本兼容（如Kubernetes v1.28支持Docker v24.0.7及以上）；
  • 调整版本：卸载不兼容的组件（如sudo apt remove docker-ce），安装符合要求的版本。