Ubuntu 上 Kubernetes 故障排查方法
一 快速定位思路
- 从集群健康入手：执行kubectl get nodes查看是否全部为Ready；如异常，使用kubectl describe node 与kubectl cluster-info dump获取事件与集群状态快照。节点被标记为NotReady通常会在约5分钟后被驱逐其上 Pod。控制平面组件日志位于**/var/log/kube-apiserver.log、kube-scheduler.log、kube-controller-manager.log**，节点侧关键日志为**/var/log/kubelet.log、kube-proxy.log**。这些能快速定位是控制面、节点还是网络问题。
- 若 kubectl 报连接被拒绝（如The connection to the server 127.0.0.1:6443 was refused），说明 API Server 未就绪或 kubeconfig 配置异常。先确认当前是否在Master节点、API Server 是否在运行（进程或容器是否存在），再检查6443端口连通性（如 curl 本地 /healthz），最后核对**–advertise-address、–bind-address**与证书有效性。
二 常见故障场景与处理
- kubectl 报 “localhost:8080 被拒绝” 或找不到配置：这是kubeconfig未正确设置。Master 节点执行：mkdir -p $HOME/.kube && cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && chown $(id -u):$(id -g) $HOME/.kube/config；Worker 节点通常没有 admin.conf，需使用 /etc/kubernetes/kubelet.conf（或集群提供的 join 配置）复制到 $HOME/.kube/config 后再试。
- 节点重启后 kubelet 未起或 kubectl 连不通：常见原因为交换分区未关闭与kubelet 未启动。执行：swapoff -a（并在**/etc/fstab中移除 swap 条目以防重启复现），随后systemctl start kubelet并检查状态。同时确保6443**未被防火墙阻断（本地可用 telnet/curl 测试）。
- Pod 长时间 Pending：优先检查节点是否NotReady或带有污点（如node.kubernetes.io/memory-pressure、disk-pressure、not-ready、unreachable），再核对nodeSelector/nodeAffinity/podAffinity/podAntiAffinity与tolerations是否导致不可调度；若报Insufficient ephemeral-storage，需清理节点或扩容磁盘；如提示pod has unbound immediate PersistentVolumeClaims，用kubectl describe pvc/pv查看事件，动态供应请确认 StorageClass bindingMode=WaitForFirstConsumer；云盘跨可用区挂载需配置节点亲和性以匹配 PV 所在可用区。
- Pod 处于 ContainerCreating：执行kubectl describe pod查看 Events，重点排查CNI 网络插件、存储卷挂载与资源配额；常见为 CNI 未就绪、PV 未绑定或节点磁盘/权限问题。
- Pod CrashLoopBackOff/Back-off restarting：先看容器日志与kubectl describe pod的 Events，常见根因包括应用崩溃、配置错误、健康检查失败、资源不足（OOMKilled）等；按需调整resources.limits/requests、健康检查参数或镜像版本。
- ImagePullBackOff/ErrImagePull：检查镜像地址与仓库可达性，确认是否需要imagePullSecrets；在节点上用**crictl pull **或 curl 验证网络连通性，必要时更换镜像仓库或凭证。
- Service 无法访问：先确认CoreDNS是否 Running，用临时 Pod dnsutils 测试解析（如 nslookup web.default.svc.cluster.local，注意命名空间与 FQDN）；若解析正常但访问 Service IP/端口不通，核对 Service 的port/targetPort、selector 与 Endpoints是否一致，再检查节点上kube-proxy是否正常运行与iptables/ipvs规则是否生效。
三 高频命令清单
- 集群与节点：kubectl get nodes -o wide；kubectl describe node ；kubectl cluster-info dump
- Pod 与事件：kubectl get pods -A -o wide；kubectl describe pod -n ；kubectl logs -c -n ；kubectl get events --sort-by=.metadata.creationTimestamp -n
- 网络与 DNS：kubectl get svc,endpoints -n ；kubectl run -it --rm dnsutils --image=busybox:1.36 --restart=Never – nslookup kubernetes.default.svc.cluster.local
- 存储：kubectl get pvc,pv -n ；kubectl describe pvc -n
- 节点侧日志与状态：sudo journalctl -u kubelet -f；sudo crictl ps -a | grep -i apiserver；sudo crictl logs ；ss -lntp | grep 6443
四 Ubuntu 与 kubeadm 场景的专项检查
- 重启后异常：优先确认swapoff -a已生效、kubelet已启动（systemctl status kubelet），以及6443端口监听与访问控制（本地 curl/ telnet 验证）。
- kubeconfig 区分：Master 用admin.conf，Worker 用kubelet.conf或集群 join 配置复制到**$HOME/.kube/config**，避免误用导致8080/6443连接错误。
- 节点加入失败：核对hostname/IP解析、kubelet服务状态与主节点连通性；必要时查看 kubelet 日志与节点 Events，确保网络、证书与 kubeconfig 一致。
