跳转至

Kubernetes 故障排查

排障的核心不是背命令，而是先定位故障层：请求是否到达入口、Service 是否有后端、Pod 是否就绪、容器是否正常、节点和依赖是否健康。先保存证据，再修改或重启，避免把根因清掉。

固定的第一轮检查

kubectl config current-context
kubectl config view --minify
kubectl get ns
kubectl get deploy,sts,ds,pod,svc,ingress -n <namespace> -o wide
kubectl get events -n <namespace> --sort-by=.lastTimestamp

先确认集群、context 和 Namespace。很多“资源不存在”只是查错了环境。然后从业务入口沿调用链逐层缩小范围。

用户请求
  → LoadBalancer / Ingress Controller / Gateway
  → Ingress / HTTPRoute 规则
  → Service
  → EndpointSlice
  → Pod IP 和端口
  → Readiness
  → 容器进程
  → 数据库、缓存、消息队列等外部依赖

Pod 为什么没有正常运行

kubectl get pod <pod> -n <namespace> -o wide
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --all-containers --tail=200
kubectl logs <pod> -n <namespace> -c <container> --previous
状态/现象 优先检查
Pending Events、requests、节点可用量、污点/容忍、亲和性、PVC、配额
ContainerCreating 镜像拉取、CNI、CSI 挂载、Secret/ConfigMap
ImagePullBackOff 镜像地址和标签、仓库 DNS/证书、imagePullSecret、节点出口
CrashLoopBackOff 当前和 --previous 日志、退出码、启动参数、依赖、探针
OOMKilled 内存 limit、堆/缓存/并发、节点内存压力；不要只盲目加 limit
Running 但不 Ready Readiness 路径/端口、启动耗时、依赖是否被健康检查绑死
Terminating 很久 preStop、terminationGracePeriod、存储卸载、finalizer

describe 适合看调度、拉镜像、挂载和探针 Events；logs 只能解释容器进程；两者不能互相替代。

发布失败与回滚

kubectl rollout status deployment/<name> -n <namespace> --timeout=5m
kubectl rollout history deployment/<name> -n <namespace>
kubectl get rs -n <namespace> -l app=<label>
kubectl diff -f manifests/
kubectl rollout undo deployment/<name> -n <namespace>

滚动发布卡住时比较新旧 ReplicaSet 的镜像、配置、资源和探针。回滚只恢复 Deployment 的 Pod Template，不会自动回滚数据库变更、外部 Secret 或不在 Template 中的配置，因此发布方案要保证兼容性。

Service、DNS 与入口故障

kubectl get svc,endpointslice -n <namespace>
kubectl describe svc <service> -n <namespace>
kubectl get pod -n <namespace> --show-labels
kubectl get ingress -n <namespace>
kubectl describe ingress <ingress> -n <namespace>
kubectl get pods -n kube-system
  1. Service selector 是否真的匹配 Pod labels。
  2. EndpointSlice 是否有地址；没有时检查 Pod Readiness。
  3. 在集群内分别测试 Pod IP、Service 名和 Service ClusterIP。
  4. 检查 <service>.<namespace>.svc DNS 解析。
  5. 再检查 IngressClass、控制器日志、路由规则、TLS Secret 和外部负载均衡。

若 Pod 到 Pod 都不通，再查 CNI Pod、节点路由、MTU、NetworkPolicy 和主机防火墙。不要一开始就把问题都归因于 Ingress。

节点、资源与调度

kubectl get nodes -o wide
kubectl describe node <node>
kubectl top node
kubectl top pod -A --containers
kubectl get pod -A --field-selector spec.nodeName=<node>

关注 Node Conditions：Ready、MemoryPressure、DiskPressure、PIDPressure、NetworkUnavailable。节点 NotReady 时还需到节点检查 kubelet、容器运行时、磁盘/inode、时间同步和到 API Server 的网络。日常维护应先 cordon、再 drain，不要直接停机。

存储与配置故障

kubectl get pvc,pv -A
kubectl describe pvc <pvc> -n <namespace>
kubectl get configmap,secret -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp
  • PVC Pending：查 StorageClass、CSI provisioner、拓扑和容量。
  • FailedMount/Attach：查 CSI 节点插件、VolumeAttachment、旧节点残留挂载。
  • CreateContainerConfigError：查 ConfigMap/Secret 名称和 key。
  • 应用配置未更新：确认是 env 还是 volume，是否需要 rollout restart。

CPU、内存和连接数

kubectl top pod -n <namespace> --containers
kubectl describe pod <pod> -n <namespace>

CPU 高要区分真实业务负载、死循环、GC、频繁重试和 CPU limit throttling；内存高要区分正常缓存、堆增长、堆外内存和泄漏。连接数问题需同时观察应用连接池、文件描述符、Service/入口连接、下游数据库或消息队列限制。Kubernetes 指标只是入口，最终仍需结合应用指标、线程/堆分析和节点指标。

安全地收集证据

kubectl get pod <pod> -n <namespace> -o yaml
kubectl logs <pod> -n <namespace> --all-containers --since=30m
kubectl get events -n <namespace> --sort-by=.lastTimestamp
kubectl auth can-i --list -n <namespace>

工单中记录发生时间、集群/Namespace、对象名、镜像版本、最近变更、错误原文和影响范围。分享 YAML、日志或 describe 输出前先清理 Secret、Token、证书和内部地址。

一条可复用的判断路线

对象不存在 → context / namespace / RBAC
对象存在但 Pod 未创建 → 控制器、selector、quota
Pod Pending → 调度、资源、污点、PVC
容器未启动 → 镜像、配置、挂载、CNI
容器反复退出 → previous logs、退出码、OOM、探针
Pod 正常但 Service 不通 → selector、EndpointSlice、端口、NetworkPolicy
集群内正常但外部不通 → Ingress/Gateway、控制器、LB、DNS、TLS
只有业务请求失败 → 应用日志、依赖、超时、连接池和数据一致性

官方参考：Debug Pods、Debug Services。