真实命令 · 少走弯路·已沉淀 95 篇排障/命令手册，25 份速查表，15 个配置工具进入排障台
LaoHand开发者排障手册
配置生成

kubernetes Troubleshooting

Kubernetes ImagePullBackOff 排查流程

Kubernetes Pod 卡在 ImagePullBackOff/ErrImagePull 时，kubectl describe pod 读取 Events 里 Failed to pull image 的完整错误，逐个排查镜像 tag 是否存在、私有仓库 imagePullSecrets 是否引用、节点到 Registry 网络、以及多架构镜像 manifest 是否匹配当前节点。

先看 describe pod 的 Events，确认是镜像不存在、认证失败、网络超时还是架构不匹配。ImagePullBackOff 是重试等待状态，不是最终根因。

适用环境Kubernetes / kubectl / 容器运行时
风险等级低
最后验证2026-06-30
建议权限普通用户

2026-06-30 更新·约 4 分钟阅读

Scenario

这篇文章解决什么问题

适用于“Kubernetes ImagePullBackOff 排查流程”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先看 describe pod 的 Events，确认是镜像不存在、认证失败、网络超时还是架构不匹配。ImagePullBackOff 是重试等待状态，不是最终根因。

Symptoms

典型现象

  • Kubernetes Pod 卡在 ImagePullBackOff/ErrImagePull 时，kubectl describe pod 读取 Events 里 Failed to pull image 的完整错误，逐个排查镜像 tag 是否存在、私有仓库 imagePullSecrets 是否引用、节点到 Registry 网络、以及多架构镜像 manifest 是否匹配当前节点。
  • 相关日志、命令或页面中反复出现 kubernetes、imagepullbackoff、registry 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

Before Debugging

排查前先确认

  • 先确认 namespace、资源名、节点、镜像和最近一次变更。
  • 按 Pod → Service/Endpoint → Ingress/外部入口的顺序定位，不要跳层。
  • 优先看 describe events 和上一轮容器日志，它们通常比状态字段更接近根因。

Root Causes

常见根因分层

控制面状态只是结果，不是根因

CrashLoopBackOff、ImagePullBackOff、Pending 都是 Kubernetes 的状态归纳。真正原因在 Events、容器退出码、镜像拉取错误或调度失败信息里。

  • describe pod 看 Events
  • logs --previous 看上一轮崩溃
  • get events 按时间线排序

标签、端口和就绪状态断链

Service selector 不匹配、targetPort 写错、readiness 未通过，会让流量入口看起来存在但没有可用后端。

  • get svc,endpoints 同看
  • 核对 Pod labels
  • 确认容器监听端口

集群网络和策略限制

DNS、NetworkPolicy、IngressClass、节点到 Registry 网络、TLS Secret 都可能让同一应用在不同 namespace 或节点表现不同。

  • 从集群内临时 Pod 测试
  • 确认 IngressClass 和 Controller 日志
  • 检查 Secret 所在 namespace

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。Kubernetes ImagePullBackOff 排查流程 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
kubectl describe pod <pod> -n <namespace>
kubectl get secret -n <namespace>

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
kubectl get secret -n <namespace>
kubectl create secret docker-registry regcred --docker-server=<registry> --docker-username=<user> --docker-password=<password> -n <namespace>
kubectl get pod <pod> -n <namespace> -o jsonpath="{.spec.imagePullSecrets}"

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

  • 读取 Events 中 Failed to pull image 后面的完整错误。
  • 确认镜像仓库、命名空间、镜像名和 tag 拼写正确。
  • 私有仓库检查 imagePullSecrets 是否在同一 namespace 并被 Pod 引用。
3. 读取服务端证据，而不是只看客户端提示
kubectl create secret docker-registry regcred --docker-server=<registry> --docker-username=<user> --docker-password=<password> -n <namespace>
kubectl get pod <pod> -n <namespace> -o jsonpath="{.spec.imagePullSecrets}"
kubectl debug node/<node> -it --image=busybox

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

  • 私有仓库检查 imagePullSecrets 是否在同一 namespace 并被 Pod 引用。
  • 节点网络异常时在节点侧测试 Registry 连通性和 DNS。
  • 多架构集群要确认镜像 manifest 支持当前节点架构。
4. 做最小修复并立即回归验证
kubectl get pod <pod> -n <namespace> -o jsonpath="{.spec.imagePullSecrets}"
kubectl debug node/<node> -it --image=busybox

Commands

排查命令与使用意图

命令 1

用于读取 Kubernetes Events、状态变化和资源引用关系。排查 Pod、Service、Ingress 时，它通常能直接暴露调度、拉镜像、探针或后端错误。

命令 1
kubectl describe pod <pod> -n <namespace>

命令 2

用于读取 Kubernetes 当前资源状态和 Events。重点看 STATUS、RESTARTS 和 Events 中的调度、探针、镜像错误。

命令 2
kubectl get secret -n <namespace>

命令 3

用于补充“Kubernetes ImagePullBackOff 排查流程”的排查证据链。kubectl 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 3
kubectl create secret docker-registry regcred --docker-server=<registry> --docker-username=<user> --docker-password=<password> -n <namespace>

命令 4

用于读取 Kubernetes 当前资源状态和 Events。重点看 STATUS、RESTARTS 和 Events 中的调度、探针、镜像错误。

命令 4
kubectl get pod <pod> -n <namespace> -o jsonpath="{.spec.imagePullSecrets}"

命令 5

用于补充“Kubernetes ImagePullBackOff 排查流程”的排查证据链。kubectl 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 5
kubectl debug node/<node> -it --image=busybox

Risk Notes

容易踩坑的地方

  • 不要直接删除有状态 Pod 或 PVC 来“试试”，先确认控制器和数据卷策略，避免数据丢失。
  • 不要只看当前容器日志，CrashLoop 场景必须看 --previous 获取上一轮崩溃的完整输出。
  • 不要在 production 集群上随意修改资源配额或节点标签，这类变更可能触发级联 Pod 调度。

Verification

修复后怎么确认

  • 原始故障现象已经消失，且使用同一入口重新测试 Kubernetes ImagePullBackOff 能稳定成功。
  • 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
  • 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。

Prevention

后续预防

  • 发布模板中强制包含 probes、资源限制和回滚策略，确保所有工作负载都有存活和就绪检查。
  • 把 Service selector、端口名和 labels 做成约定，减少手写漂移导致的网络断链问题。
  • 为镜像拉取、Pod 重启和 Ingress 5xx 建立基础告警，第一时间发现异常。
  • 定期用 kubectl cluster-info dump 和容器运行时检查集群健康状态，提前发现调度和资源问题。

常见问题

ErrImagePull 和 ImagePullBackOff 有什么区别？

ErrImagePull 是刚拉取失败的错误，ImagePullBackOff 是 Kubernetes 进入退避重试后的状态。都需要看 Events 里的真实原因。

Secret 已创建为什么还是拉不下来？

常见原因是 Secret 不在同一 namespace、Pod 没引用 imagePullSecrets，或仓库地址和 Secret server 字段不一致。

Long-tail SEO

你可能正在搜索这些报错

下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。

  • Kubernetes ImagePullBackOff
  • ErrImagePull pull access denied
  • kubectl describe pod image pull
  • K8s imagePullSecrets 配置
  • registry credentials Kubernetes
  • docker manifest unknown k8s
  • Kubernetes 拉镜像超时
  • Back-off pulling image

Related

相关排障 / 命令 / 工具

按分类和标签关联的排障流程、命令模板和配置工具，方便顺着同一个问题继续往下查。

速查

kubectl 常用命令速查表

kubectl 常用命令一页速查：get/describe/logs/exec 现场调试、scale 与 rollout 更新回滚、context 与 namespace 切换、events 事件筛查，覆盖 Pod CrashLoop 和 ImagePullBackOff 排障主路径。

kubernetes命令

kubectl 排查 Pod 状态常用命令

kubectl 排查 Pod 异常的核心命令组合，kubectl get pod 看状态与重启次数、describe pod 看调度/拉镜像/探针/OOM 事件、logs --tail=200 读近期日志，CrashLoopBackOff 场景加 --previous 读上一轮崩溃日志，exec -it 进容器复现问题。

kubernetes排障

Kubernetes Pod CrashLoopBackOff 排查流程

Kubernetes Pod 陷入 CrashLoopBackOff、Back-off restarting failed container 时，用 kubectl logs --previous 读取上一轮崩溃日志，kubectl describe pod 看 Last State/Exit Code/OOMKilled，逐个排查应用启动错误、liveness 探针误杀、ConfigMap/Secret 挂载缺失和内存限制。

kubernetes命令

kubectl 排查 Service 和 Ingress 命令

kubectl 排查 Kubernetes Service 与 Ingress 路由不通的常用命令，kubectl get svc,endpoints 看 endpoints 是否为空判断 selector 是否匹配，describe ingress 看 rules 和 IngressClass，用 curl -H Host 复现入口路由并核对 targetPort 与容器端口。

kubernetes排障

Kubernetes Ingress 404/502 排查流程

Kubernetes Ingress 返回 404 或 502 时，用 curl -H Host 精确复现路由，再 kubectl describe ingress 检查 rules/pathType/IngressClass，404 多为 host 或 path 没命中，502 多为 Service Endpoints 为空或 targetPort、Pod readiness 有问题。

kubernetes排障

Kubernetes Service 访问不通排查

Kubernetes Service 通过 ClusterIP/NodePort 访问不通时，先 kubectl get endpoints 看是否为空——空则是 selector 与 Pod labels 不匹配，有值再核对 targetPort、Pod readiness 和 NetworkPolicy，最后用 busybox nslookup 验证集群 DNS 是否解析 svc.cluster.local。

kubernetes