Ubuntu 上 Kubernetes 故障排查实操手册
一 快速定位路径
- 查看全局状态：使用kubectl get nodes -o wide确认节点是否Ready；用kubectl get pods -A查看所有命名空间 Pod 状态；对异常对象执行kubectl describe获取事件；查看容器日志用kubectl logs -n [-c ]，崩溃可加**–previous**；节点侧关键日志用journalctl -u kubelet -f实时跟踪。若节点 NotReady，优先检查 kubelet、容器运行时与网络插件。
- 节点资源与系统健康：执行df -h /var/lib/kubelet（建议保留至少10%空闲）、free -m、top -p $(pgrep kubelet)；检查内核与系统日志dmesg -T | grep -i "oom|error"与journalctl -xe，关注OOM、磁盘压力、服务崩溃等。
二 节点与系统层排查
- kubelet 与容器运行时：确认服务运行systemctl status kubelet，异常时journalctl -u kubelet -f定位（证书、运行时、磁盘等）；容器运行时（containerd/docker）检查systemctl status containerd，containerd 可用ctr containers list查看容器；若 kubelet 配置异常，核对**/etc/kubernetes/kubelet.conf或/var/lib/kubelet/config.yaml中的clusterDNS（如 10.96.0.10）、clusterDomain（如 cluster.local）、runtimeEndpoint（containerd 一般为unix:///run/containerd/containerd.sock**）。
- 容器运行时关键参数与镜像：containerd 配置**/etc/containerd/config.toml中sandbox_image**（如国内镜像registry.aliyuncs.com/google_containers/pause:3.9）与SystemdCgroup=true；修改后执行containerd config default > /etc/containerd/config.toml并重启systemctl restart containerd。
- 磁盘与镜像清理：当**/var或/var/lib/kubelet使用率超过80%时，清理旧日志（/var/log）、无用镜像（docker system prune或crictl rmi --prune**）与临时文件，避免 kubelet/运行时异常。
三 Pod 与容器常见故障
- 状态与事件：对异常 Pod 用kubectl describe pod -n 查看Events（如Insufficient CPU、Failed to pull image、Unhealthy）；结合kubectl logs与**–previous**定位应用错误。
- 典型症状处理：
- ImagePullBackOff/ErrImagePull：核对镜像名与标签（如nginx:1.25），私有仓库配置imagePullSecrets；本地先docker pull验证。
- CrashLoopBackOff：查看日志与探针（livenessProbe/readinessProbe）配置，必要时调整initialDelaySeconds、启动命令或依赖服务可用性。
- Pending：资源不足或亲和性不匹配，检查resources.requests/limits、节点资源与调度约束。
- OOMKilled：提升resources.limits.memory（如512Mi），并合理设置requests避免碎片。
- Ports not available：确认containerPort与应用监听端口一致，Service 的targetPort匹配容器端口。
四 Service 与网络排查
- Service 与 Endpoints：用kubectl get svc -n 核对CLUSTER-IP与PORT(S)；用kubectl describe svc -n 核对selector；用**kubectl get endpoints -n **确认是否关联到 Pod IP:Port（为空多为 selector 不匹配）。
- 连通性与防火墙：节点侧测试到 API Server：ping 与nc -zv 6443；排查ufw/iptables与安全组规则。
- CNI 与网络策略：检查 CNI Pod（如calico-node/flannel）状态与日志，确认BGP/隧道就绪；用kubectl get networkpolicies -A排查策略阻断。
- DNS 解析：确认CoreDNS运行（kubectl get pods -n kube-system -l k8s-app=kube-dns），在集群内临时容器测试nslookup .；节点**/etc/resolv.conf应指向CoreDNS ClusterIP（默认 10.96.0.10）**。
五 证书 组件 与恢复
- 证书有效期：检查kubelet客户端证书openssl x509 -in /var/lib/kubelet/pki/kubelet-client-current.pem -noout -dates；集群证书用kubeadm certs check-expiration，将过期证书及时更新。
- 控制面组件：查看kube-apiserver/etcd/controller-manager/scheduler/kube-proxy/CoreDNS是否Running，异常时用kubectl describe pod -n kube-system与日志定位。
- 重置与重装：无法恢复时先备份清单与密钥，再执行sudo kubeadm reset清理节点，随后按需要kubeadm init或使用现有清单重新加入集群。
