Kubernetes 资源故障排查

排障先保留现场，再收集证据，最后修改。不要一看到 Pod 异常就删除或重启，它可能抹掉退出码、事件和上一次容器日志。本章建立固定的排障路径，覆盖最常见的 Pod、网络与存储问题。

本篇目标：建立 Golden Signals 与层级递进的排错方法论，掌握 describe/logs/debug 等诊断工具，能定位 ImagePullBackOff、CrashLoopBackOff、OOMKilled、Pending 等典型异常。

1. 排错方法论：Golden Signals 与层级递进法

1.1 Golden Signals：先看"多严重"

排障前先量化影响面，避免一上来就钻进某个 Pod：

1.2 层级递进法

影响范围
  -> 工作负载期望副本是否满足
  -> Pod 状态、事件、容器日志
  -> Service / DNS / 网络路径
  -> Node、调度、存储和集群组件
  -> 修复后业务与平台双重验证

先判断是单 Pod、单服务、单 Namespace、单 Node 还是全局问题。范围越大，越应优先检查近期集群变更、节点状态、入口和 DNS，而不是单个应用 YAML。

2. 高频排错诊断工具与命令

2.1 第一轮证据采集

# 看工作负载是否维持期望副本
kubectl get deployment,statefulset,daemonset -n <namespace>

# 看 Pod 位置、重启次数与状态
kubectl get pods -n <namespace> -o wide

# 看调度、拉镜像、挂载和探针事件
kubectl describe pod <pod-name> -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp

# 当前和上一次崩溃容器的日志
kubectl logs <pod-name> -n <namespace> -c <container> --tail=200
kubectl logs <pod-name> -n <namespace> -c <container> --previous --tail=200

多容器 Pod 必须明确 -c。--previous 只在容器已经重启过时有意义，是排查 CrashLoopBackOff 的关键证据。

2.2 退出码速查

退出码是判断崩溃原因的第一线索：

kubectl get pod <pod-name> -n <namespace> \
  -o jsonpath='{.status.containerStatuses[*].lastState.terminated.exitCode}'

2.3 进入现场

# 精简镜像无 shell 时，注入临时调试容器
kubectl debug <pod-name> -n <namespace> \
  --image=netshoot:v0.16 \
  --target=<container-name> \
  -it -- sh

# 或创建调试副本（不侵入原 Pod）
kubectl debug <pod-name> -n <namespace> \
  --image=busybox:1.36 \
  --copy-to=debug-pod \
  -it -- sh

netshoot 镜像（nicolaka/netshoot）预装了 tcpdump、iperf、ethtool、iptables 等全套网络诊断工具。

3. 典型 Pod 异常定位

3.1 异常状态速查

3.2 Pending 深度定位

kubectl describe pod <pod-name> -n <namespace> | grep -A5 Events
# 典型输出：
#   FailedScheduling: 0/3 nodes are available: 1 Insufficient cpu, 2 node(s) had taint...

• Insufficient cpu/memory → 检查 Node 资源余量 kubectl top nodes，调小 request 或扩容；
• node(s) had taint → 检查 Pod 是否有对应 toleration（第 18 章）；
• node(s) didn't match Pod's node affinity → 检查 nodeSelector / affinity 与 Node 标签；
• PVC not found 或 storage class not found → 检查 PVC 和 StorageClass（第 12-13 章）；
• exceeded quota → Namespace 配额不足（第 3 章）。

3.3 ImagePullBackOff 深度定位

kubectl describe pod <pod-name> -n <namespace> | grep -A10 Events

4. 网络与存储连接性排查路径

4.1 网络排查

# 启动临时调试 Pod
kubectl run tmp --image=busybox:1.36 --rm -it --restart=Never -- sh
# 进入后：
nslookup svc-name.namespace      # DNS
wget -q -O- http://svc:port/     # HTTP
nc -zv svc-name 3306             # TCP 端口

Service 不通时按顺序排查：

1. EndpointSlice 无地址 → selector 不匹配或 Pod 未 Ready；
2. EndpointSlice 正常但 wget 不通 → 容器监听端口、NetworkPolicy、CNI；
3. 集群内可通但外部不通 → Ingress/Gateway 规则、外部 DNS、安全组、负载均衡。

4.2 DNS 排查

kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns --tail=50
kubectl get configmap coredns -n kube-system -o yaml

常见 DNS 故障模式：

• CoreDNS Pod 不健康 → 所有服务间 DNS 解析失败；
• CoreDNS ConfigMap 配置错误 → 特定域名解析异常；
• Pod 的 dnsPolicy 设置不当 → 部分 Pod 解析不到内部 Service；
• NetworkPolicy 阻断 UDP 53 → DNS 超时。

4.3 存储排查

kubectl describe pvc <pvc-name> -n <namespace>
kubectl get pv
kubectl describe pod <pod-name> -n <namespace> | grep -A5 Events

• PVC Pending → 参考第 13 章排障表；
• Pod 挂载失败 → 检查访问模式、跨 AZ、fsGroup 权限；
• 节点 DiskPressure → 清理磁盘或扩容，见下节。

4.4 节点与集群问题

kubectl get nodes -o wide
kubectl describe node <node-name>

节点问题可能同时影响多个无关应用。先停止在该节点继续发布或调度新工作负载（cordon），再按平台运行手册处置。

5. 调试工具的边界

• kubectl exec 适合镜像内已有诊断工具的场景（如 bash、curl）；
• 精简镜像用 kubectl debug 注入临时容器，但它可能需要较高权限，也可能接触生产数据和网络——使用受控镜像、最小权限和变更留痕；
• 导出日志和事件到本地做离线分析，减少对生产集群的操作频次；
• 排障结论要沉淀：把每次故障的"现象 → 证据 → 根因 → 修复"记录成检查项，下一次更快。

6. 练习

练习 A

1. 创建一个 Deployment，镜像用不存在的 tag（如 nginx:999.999），观察 Pod 进入 ImagePullBackOff
2. 用 kubectl describe pod 和 kubectl get events 定位原因
3. 创建第二个 Deployment，容器命令为 sleep 5 && exit 1，观察 CrashLoopBackOff，用 logs --previous 取证

练习 B

1. 用 busybox 启动一个临时 Pod，分别用 nslookup、wget 测试集群内部 Service 的连通性
2. 创建一个 Service selector 故意与 Pod labels 不匹配的情况，用 get endpointslice 验证无后端
3. 修复 selector，观察 EndpointSlice 出现地址
4. 把 memory limit 设到 8Mi 并运行一个吃内存的程序，观察 OOMKilled，练习退出码 137 的取证

下一篇：Kubernetes 资源生产实践。