K8s 全场景常见问题完整排查手册

核心概念 K8s 全场景故障排查手册，覆盖 Pod 异常、节点故障、网络问题、存储问题、集群组件问题等。

覆盖：Pod 启动失败、调度失败、网络不通、存储挂载异常、Service/Ingress 访问失败、集群控制平面故障、资源性能、集群异常、日志监控、镜像权限、安全策略。

1. Pod 无法正常启动（最高频）

1.1. 排查标准三步走

# 1. 查看Pod基础状态、事件（核心！）
kubectl get pod xxx -o wide
kubectl describe pod xxx

# 2. 查看容器日志
kubectl logs pod-name [-c 容器名] --previous # --previous 查看崩溃前日志

# 3. 进入容器调试（若容器能短暂拉起）
kubectl exec -it pod-name -- /bin/sh

1.2. 细分故障原因 & 解决方案

1.2.1. （1）镜像拉取失败 ImagePullBackOff

报错关键词：ErrImagePull、ImagePullBackOff
诱因：

1. 镜像名称/标签写错；
2. 私有仓库无秘钥 Secret（imagePullSecrets）；
3. 节点无法连通镜像仓库（防火墙、内网不通）；
4. 镜像不存在、镜像损坏、镜像架构不匹配(arm/amd64)。
   修复：

• 核对镜像地址；创建 dockerconfigjson 私有仓库密钥绑定到ServiceAccount；
• 节点测试 docker pull 验证连通性。

1.2.2. （2）资源不足 Pending，调度失败

describe 事件提示：Insufficient cpu/memory
节点整机CPU/内存不够调度该Pod。
解决：

1. 降低Pod requests；
2. 扩容Worker节点；
3. 清理无用释放资源。

1.2.3. （3）污点/亲和策略无法调度

报错：Taints and tolerations、nodeAffinity/nodeAntiAffinity

1. 节点有污点，Pod无对应容忍tolerations；
2. Pod节点亲和/反亲和匹配不到可用节点；
3. 专属节点池标签不匹配。

1.2.4. （4）镜像拉起后立刻崩溃 CrashLoopBackOff

1. 健康探针配置错误：liveness/readiness 端口/路径错误，持续杀死容器；
2. 启动命令错误：CMD/ENTRYPOINT 执行直接退出；
3. 权限不足：容器以非root运行，但需要读写挂载目录；镜像内文件权限000；
4. 配置缺失：ConfigMap/Secret key不存在、环境变量为空导致程序启动失败；
5. 存储挂载冲突：volumeMount 目录与容器内置文件冲突覆盖；
6. 程序OOM被杀：OOMKilled，调大容器limits内存。

排查：kubectl logs --previous 看崩溃堆栈。

1.2.5. （5）容器创建报错 CreateContainerConfigError

常见：Secret/ConfigMap不存在、权限配置错误、securityContext非法、capabilities 不支持。

1.2.6. （6）镜像无shell无法exec进入

基础镜像是distroless/scratch，无/bin/sh。
调试方案：

# 临时使用调试镜像替换启动
kubectl debug pod-name -it --image=busybox

2. 调度相关故障（Pod一直Pending）

2.1. 核心看 describe pod Events 事件，分为几类

1. 资源不足：Insufficient cpu/memory/gpu
2. 污点不匹配：node had taint xxx that pod did not tolerate
3. 亲和规则不满足：node affinity/ pod anti-affinity 无符合节点
4. 端口冲突：节点主机端口被占用（hostPort）
5. PVC 未绑定：PVC处于Pending，StorageClass无法创建PV

2.2. 节点NotReady导致无法调度

节点状态 NotReady，kubectl get node 查看
常见：

1. kubelet 挂掉；
2. CNI网络插件异常（Calico/Cilium Pod Crash）；
3. 节点磁盘压力过大，磁盘压力污点 node-conditions；
4. 节点内存/磁盘满，kubelet标记节点不可调度。

修复：

# 登录节点重启kubelet
systemctl restart kubelet containerd
# 查看节点污点
kubectl describe node xxx | grep Taint

3. 存储 PV/PVC 挂载失败

3.1. PVC 一直 Pending

1. 未配置 StorageClass，无默认SC；
2. 存储后端故障（云盘API异常、Ceph离线）；
3. 存储配额耗尽、云账号权限不足无法创建云盘；
4. 存储类绑定的节点池不存在。

3.2. Pod 报错：volume mount failed

1. Secret/ConfigMap key名称写错；
2. 宿主机目录权限不足（bind mount、LocalPV）；
3. CSI插件Pod异常，无法挂载磁盘；
4. 云盘已被其他节点占用，未释放；
5. 只读挂载 :ro 但程序需要写权限。

3.3. StatefulSet PVC 残留

缩容STS只会删Pod，PVC保留；重建Pod会复用旧PVC，如需全新数据手动删除PVC。

4. 网络类故障（访问不通、Service 5xx、Ingress异常）

4.1. Pod 之间互相 ping/访问不通

排查顺序：

1. CNI插件是否全部Ready：kubectl get ds -n kube-system calico/cilium；
2. 检查NetworkPolicy 拦截了端口/网段；
3. 查看Pod IP是否分配正常，是否同一网段；
4. 容器内部防火墙 iptables 拦截。

4.2. ClusterIP Service 无法访问

1. Service selector 标签和Pod labels 不匹配（最常见）

# 核对service标签匹配
kubectl describe svc xxx | grep Selector
kubectl get pod --show-labels

2. 后端Pod未就绪（readiness探针失败，未加入Service端点）

# 查看Service后端就绪端点
kubectl get ep xxx

3. kube-proxy异常：iptables/ipvs规则未生成；
4. 本地DNS解析异常：进入Pod nslookup svc-name.ns.svc.cluster.local

4.3. NodePort/LoadBalancer 外网访问不通

1. 安全组/防火墙未放行NodePort端口；
2. Service后端Pod全部未就绪，ep为空；
3. MetalLB BGP/L2分配VIP失败；
4. 云厂商NLB后端健康检查失败，剔除节点。

4.4. Ingress 无法访问、404/502

1. Ingress 后端Service名称/端口写错；
2. Service ep无就绪Pod；
3. Ingress控制器Pod崩溃（nginx-ingress/cilium）；
4. 域名、路径匹配规则错误；
5. TLS证书Secret不存在、证书过期。

4.5. DNS解析异常（nslookup失败）

1. coredns Pod崩溃：kubectl get pod -n kube-system coredns；
2. CoreDNS ConfigMap 配置错误；
3. Pod dnsPolicy 配置异常；
4. 大量并发DNS请求打满coredns，可扩容coredns副本。

5. 控制平面 Master 集群故障（apiserver/etcd/controller/scheduler）

5.1. kubectl 命令报错 unable to connect server

1. apiserver LB地址不通；
2. 3台Master apiserver 进程崩溃；
3. 证书过期、kubeconfig 证书失效；
4. 防火墙拦截6443端口。

5.2. etcd 异常（集群核心，所有资源读写失败）

报错：etcd connection refused、raft leader丢失
排查：

# 查看etcd Pod状态
kubectl get pod -n kube-system etcd-xxx
# 进入etcd查看集群健康
etcdctl endpoint health --cacert=xxx

诱因：

1. etcd 磁盘SSD损坏、IO阻塞；
2. 集群节点失联，超过半数宕机集群不可用；
3. 证书过期、wal日志损坏；
4. 未定时快照备份，磁盘占满。

5.3. Deployment 无法创建/更新、副本不扩容

controller-manager 异常：

1. controller-manager Pod Crash；
2. 领导者选举失败，无active主控制器；
3. RBAC权限不足，控制器无法操作Pod资源。

5.4. 调度失败，Pod一直pending但资源充足

kube-scheduler 宕机，无组件负责调度Pod。

6. 资源性能问题（CPU/内存高、响应慢、OOM）

6.1. Pod OOMKilled 内存溢出

现象：容器被系统杀死，状态OOMKilled
处理：

1. 调高容器 limits.memory；
2. 优化程序内存泄漏；
3. 拆分大实例为多副本分摊内存。

6.2. CPU 持续打满

1. 程序业务逻辑耗CPU；
2. 探针频繁失败无限重启；
3. 容器无CPU限制，抢占整机资源；
   优化：配置合理 requests/limits，HPA弹性扩容。

6.3. 磁盘占用过高，节点变为不可调度

节点磁盘使用率超过阈值，kubelet添加磁盘压力污点：

1. 容器日志持续打满（未配置日志轮转）；
2. 镜像堆积，无用镜像占用磁盘；
3. EmptyDir临时缓存未清理。

7. 配置类故障 ConfigMap / Secret

1. 挂载后文件为空：key名称书写错误；
2. 更新ConfigMap，Pod不自动加载：ConfigMap更新不会热更容器内文件，需滚动重启Deployment；
3. Secret权限过大报错：容器Secret目录默认400，程序需要读权限；
4. Secret明文敏感信息，日志泄露风险。

8. 发布更新故障（Deployment滚动更新卡住）

1. 新镜像Pod无法启动，readiness探针失败，更新停滞；
2. maxUnavailable=0，旧Pod等待新Pod就绪，新Pod起不来导致卡住；
3. 资源不足无法创建新副本；
4. 旧Pod无法正常终止，terminationGracePeriodSeconds 超时卡住。

回滚方案：

kubectl rollout undo deployment xxx
# 查看更新事件
kubectl rollout status deploy xxx

9. 权限 RBAC 权限不足报错

报错关键词：forbidden: User xxx cannot resource xxx

1. ServiceAccount 未绑定对应Role/RoleBinding；
2. ClusterRole 资源操作权限缺失（create/get/update/delete）；
3. Pod 未指定serviceAccountName，使用默认无权限sa。

排查：

# 模拟Pod内权限校验
kubectl auth can-i get pods --as=system:serviceaccount:ns:sa-name

10. 通用标准化排查流程（线上固定步骤）

10.1. 场景1：Pod异常

1. kubectl get pod 看状态（Pending/Error/CrashLoopBackOff/Running）
2. kubectl describe pod 查看Events事件（90%问题在这里有提示）
3. kubectl logs / logs —previous 查看崩溃日志
4. 检查yaml：镜像、探针、资源、亲和、存储、标签

10.2. 场景2：访问服务不通

1. 检查Deployment副本是否正常running，就绪探针ok
2. 检查Service selector匹配Pod标签
3. kubectl get ep 确认后端endpoint存在
4. Pod内nslookup测试svc域名解析
5. 检查NetworkPolicy、防火墙、安全组
6. 检查kube-proxy/CNI网络插件状态

10.3. 场景3：集群控制平面异常

1. 检查etcd集群健康状态
2. 检查apiserver、controller-manager、scheduler Pod运行状态
3. 检查LB连通性、证书有效期
4. 查看对应组件日志

11. 高频排查命令汇总

# 资源基础查看
kubectl get node,pod,svc,ep,pvc,deploy,ds,cm,secret -A

# 详情事件（最核心）
kubectl describe pod <pod-name>
kubectl describe node <node-name>
kubectl describe svc <svc-name>

# 日志
kubectl logs <pod>
kubectl logs --previous <pod>

# 网络调试
kubectl exec -it <pod> -- nslookup xxx.svc.cluster.local
kubectl debug <pod> --image=busybox

# 发布管理
kubectl rollout status deploy xxx
kubectl rollout undo deploy xxx

# 权限校验
kubectl auth can-i get pods --as=sa-name

# 集群组件状态
kubectl get pods -n kube-system
kubectl get cs # 控制平面健康（旧版本）

12. 面试高频故障速记

1. Pod CrashLoopBackOff：优先看—previous日志，探针、权限、启动命令、OOM四大根因；
2. Pod ImagePullBackOff：私有仓库secret、镜像名、网络连通；
3. Pod Pending：资源不足、污点亲和、PVC未绑定、节点NotReady；
4. Service访问404/不通：selector标签不匹配、ep无就绪Pod、coredns/kube-proxy异常；
5. 滚动更新卡住：新Pod就绪探针失败、资源不足；
6. 外网访问NodePort失败：安全组/防火墙放行端口；
7. OOMKilled：内存limits过小、程序内存泄漏；
8. 控制平面kubectl连不上：apiserver LB、证书、etcd集群崩溃；
9. 存储挂载失败：SC异常、CSI插件故障、目录权限、PVC未绑定；
10. 域名解析失败：coredns Pod异常、网络策略拦截53端口。

关联文档

• K8s 发布故障排查
• K8s 故障排查面试题
• Deployment 完整深度详解
• kubectl 命令全详解