Kubernetes Pod 故障排查：全面指南

Kubernetes Pod 故障排查与其说是记住每个状态，不如说是学习 Kubernetes 在哪里留下了线索。Pod 几乎不会“静默”失败。调度器、kubelet、容器运行时、镜像仓库、卷插件以及你的应用程序都会在不同的地方留下痕迹。关键在于按正确顺序检查它们，这样你就不会花二十分钟去阅读一个从未拉取过镜像的 Pod 的应用日志。

我通常从一个问题开始：Pod 是在容器启动前、容器启动过程中，还是应用程序开始运行后失败的？这个简单的划分能让调查保持清晰。Pending 通常指向调度、存储或镜像设置问题。ImagePullBackOff 指向仓库路径、标签、凭证或节点出口。CrashLoopBackOff 通常意味着进程启动然后退出，但原因可能是配置、缺少文件、命令错误、依赖失败或内存压力。

Pod 诊断的三大支柱

故障排查始于使用三个主要的 kubectl 命令来收集关于失败 Pod 的所有可用信息。

1. 初始状态检查 (`kubectl get pods`)

第一步始终是确定 Pod 及其容器的当前状态。请密切关注 STATUS 和 READY 列。

kubectl get pods -n my-namespace

解读 Pod 状态

状态	含义	初始操作
Running	至少一个容器正在运行；这并不总是意味着应用正在提供服务。	检查 READY、重启次数和就绪事件。
Pending	Pod 已被 Kubernetes 接受，但容器尚未创建。	检查调度事件或镜像拉取状态。
CrashLoopBackOff	容器启动、崩溃，Kubelet 反复尝试重启它。	检查应用日志 (`kubectl logs --previous`)。
ImagePullBackOff	Kubelet 无法拉取所需的容器镜像。	检查镜像名称、标签和仓库凭证。
Error	Pod 因运行时错误或启动命令失败而退出。	检查日志和 `describe` 事件。
Terminating/Unknown	Pod 正在关闭或 Kubelet 主机无响应。	检查节点健康状态。

2. 深度检查 (`kubectl describe pod`)

如果状态不是 Running，describe 命令会提供关键上下文，详细说明调度决策、资源分配和容器状态。

kubectl describe pod [POD_NAME] -n my-namespace

重点关注输出中的以下部分：

Containers/Init Containers： 检查 State（特别是 Waiting 或 Terminated）和 Last State（通常记录失败原因，例如 Reason: OOMKilled）。
Resource Limits： 验证 Limits 和 Requests 是否正确设置。
Events： 这是最关键的部分。事件显示了生命周期历史，包括调度失败、卷挂载问题和镜像拉取尝试。

提示： 如果 Events 部分显示类似“0/N nodes available”的消息，Pod 很可能由于资源（CPU、内存）不足或亲和性规则未满足而无法调度。

从底部向上阅读事件以获取最新线索，但不要忽略较早的事件。一个 Pod 可能不止一个问题。例如，部署可能因请求的内存过高而开始于 FailedScheduling，然后在添加节点后转为 ImagePullBackOff。如果你只查看最终状态，可能会错过推动问题向前发展的变化。

3. 查看日志 (`kubectl logs`)

对于运行时应用程序问题，日志提供了解释进程终止原因的堆栈跟踪或错误消息。

# 检查当前容器日志
kubectl logs [POD_NAME] -n my-namespace

# 检查 Pod 内特定容器的日志
kubectl logs [POD_NAME] -c [CONTAINER_NAME] -n my-namespace

# 对 CrashLoopBackOff 至关重要：检查上一次失败运行的日志
kubectl logs [POD_NAME] --previous -n my-namespace

如果 Pod 有 sidecar，始终包含 -c。许多令人沮丧的调查都源于读取了健康 sidecar 的日志，而不是失败的应用容器。对于 init 容器失败，也使用 init 容器名称加上 -c：

kubectl logs [POD_NAME] -c [INIT_CONTAINER_NAME] -n my-namespace

常见的 Pod 故障场景及解决方案

大多数 Pod 故障都属于几种可识别的模式，每种都需要有针对性的诊断方法。

场景 1：CrashLoopBackOff

这是最常见的 Pod 故障。它表示容器成功启动，但容器内的应用程序立即退出（返回非零退出码）。

诊断：

使用 kubectl logs --previous 查看回溯或退出原因。
使用 kubectl describe 检查 Last State 部分中的 Exit Code。

常见原因及修复：

退出码 1/2： 一般应用程序错误、缺少配置文件、数据库连接失败或由于错误输入导致的应用程序崩溃。
- 修复： 调试应用程序代码或检查挂载的 ConfigMaps/Secrets。
缺少依赖： 入口点脚本需要的文件或环境不存在。
- 修复： 验证 Dockerfile 和镜像构建过程。
错误的命令或参数： 容器镜像是有效的，但 Pod 规范中的命令错误地覆盖了镜像入口点。
- 修复： 比较 Deployment 的 command 和 args 与镜像的预期启动命令。如果可能，在本地测试相同的镜像。
探针引起的重启： 存活探针可能会在慢启动应用完成预热之前将其杀死。
- 修复： 增加 initialDelaySeconds，使用 startupProbe，或将探针指向一个更轻量的健康端点。

一个实用的模式是部署一个使用相同镜像但带有无害命令的临时副本，然后检查文件系统和环境：

kubectl run debug-image \
  --image=registry.example.com/app:tag \
  --restart=Never \
  --command -- sleep 3600

kubectl exec -it debug-image -- /bin/sh

这并不能替代修复 Deployment，但它有助于快速回答简单问题：配置文件是否真的在镜像中，二进制文件是否存在，容器是否有预期的 shell，以及环境变量是否存在？

场景 2：ImagePullBackOff / ErrImagePull

当 Kubelet 无法获取 Pod 定义中指定的容器镜像时，会发生此错误。

诊断：

检查 kubectl describe 的 Events 部分，查找具体的错误消息（例如 404 Not Found 或 authentication required）。

常见原因及修复：

拼写错误或标签错误： 镜像名称或标签不正确。
- 修复： 更正 Deployment 或 Pod 规范中的镜像名称。
私有仓库访问： 集群没有从私有仓库（如 Docker Hub、GCR、ECR）拉取镜像的凭证。
- 修复： 确保在 Pod 规范中引用了适当的 imagePullSecret，并且该 Secret 存在于命名空间中。

# 使用拉取密钥的 Pod 规范示例片段
spec:
  containers:
  ...
  imagePullSecrets:
  - name: my-registry-secret

还要检查拉取密钥所在的位置。Kubernetes 密钥是命名空间隔离的。在 default 命名空间中名为 regcred 的密钥对 payments 命名空间中的 Pod 没有帮助。如果相同的镜像在一个命名空间中有效，但在另一个命名空间中失败，请在假设仓库损坏之前比较服务帐户和镜像拉取密钥：

kubectl get serviceaccount default -n payments -o yaml
kubectl get secret regcred -n payments

场景 3：Pending 状态（卡住）

Pod 保持 Pending 状态，通常表示它无法调度到节点上，或者正在等待资源（如 PersistentVolume）。

诊断：

运行 kubectl describe 并查看 Events 部分。

常见原因及修复：

资源耗尽： 集群缺少具有足够可用 CPU 或内存来满足 Pod requests 的节点。
- 修复： 增加集群规模，或减少 Pod 资源请求（如果可行）。
- 事件消息示例： 0/4 nodes are available: 4 Insufficient cpu.
卷绑定问题： Pod 需要一个无法绑定到底层 PersistentVolume (PV) 的 PersistentVolumeClaim (PVC)。
- 修复： 检查 PVC 的状态 (kubectl get pvc) 并确保 StorageClass 正常运行。
选择器或亲和性不匹配： Pod 请求的节点标签不存在，或者必需的亲和性规则排除了所有节点。
- 修复： 使用 kubectl get nodes --show-labels 比较 nodeSelector、nodeAffinity 和节点标签。
未容忍的污点： 节点可用，但由于 Pod 缺少匹配的容忍度而排斥它。
- 修复： 向 Pod 添加预期的容忍度，或者如果污点不再代表真实的放置规则，则将其移除。

场景 4：OOMKilled（因内存不足被杀死）

虽然这通常会导致 CrashLoopBackOff 状态，但其根本原因是特定的：容器使用的内存超过了其规范中定义的限制，导致主机操作系统（通过 Kubelet）强制终止它。

诊断：

检查 kubectl describe -> Last State -> Reason: OOMKilled。

修复：

增加限制： 增加 Pod 规范中的内存 limit，提供更多余量。
优化应用程序： 分析应用程序以减少其内存占用。
设置请求： 确保 requests 设置接近实际的稳态使用量，以提高调度可靠性。

resources:
  limits:
    memory: "512Mi" # 增加此值
  requests:
    memory: "256Mi"

小心那些仅提高限制的内存“修复”。如果应用程序存在泄漏，更高的限制可能只会延迟下一次故障，并使节点承担更多风险。在你的指标系统中查看一段时间内的内存使用情况。垃圾回收后恢复到基线的锯齿模式与持续攀升直至 OOM 的模式不同。

场景 5：CreateContainerConfigError 和 CreateContainerError

这些状态很容易被忽略，因为它们听起来不像应用程序故障。它们通常意味着 kubelet 无法组装容器配置。

常见原因包括：

引用的 ConfigMap 或 Secret 在命名空间中不存在。
ConfigMap 或 Secret 中的键拼写错误。
卷挂载路径与另一个挂载冲突。
容器引用了无效的安全上下文。

最快的检查方法仍然是 describe：

kubectl describe pod [POD_NAME] -n my-namespace

查找类似 secret "app-config" not found 或 configmap "settings" not found 的事件消息。然后验证对象：

kubectl get secret app-config -n my-namespace
kubectl get configmap settings -n my-namespace -o yaml

这是一个常见的部署管道错误。应用清单已应用，但密钥创建步骤失败或针对了错误的命名空间。

场景 6：运行但未就绪

Pod 可以显示 Running 但仍然不可用。READY 列告诉你根据就绪探针有多少容器已就绪。1/2 或 0/1 的 Pod 可能处于活动状态，但已从 Service 端点中移除。

当流量失败但 Pod 看起来存活时，检查端点：

kubectl get endpoints [SERVICE_NAME] -n my-namespace
kubectl describe pod [POD_NAME] -n my-namespace

如果端点列表为空，问题可能是就绪探针、Service 选择器不匹配，或者应用程序监听的端口与 Service 期望的端口不同。在实际事件中，这是人们浪费时间的地方：他们不断重启 Pod，即使 Pod 并不是流量缺失的原因。

预防未来故障：最佳实践

健壮的应用程序需要仔细配置，以防止常见的部署陷阱。

使用存活和就绪探针

正确实现探针使 Kubernetes 能够智能地管理容器健康：

存活探针： 确定容器是否健康到足以继续运行。如果存活探针失败，Kubelet 将重启容器（解决软锁）。
就绪探针： 确定容器是否已准备好提供服务流量。如果就绪探针失败，Pod 将从 Service 端点中移除，防止在容器恢复期间出现失败的请求。

不要将存活探针指向深度依赖检查，除非你真的希望 Kubernetes 在依赖项发生短暂中断时重启容器。数据库不可用三十秒通常不能证明进程已死。就绪探针是更好的位置，用来表示“现在不要向此 Pod 发送流量”。

强制资源限制和请求

始终为容器定义资源需求。这可以防止 Pod 消耗过多资源（导致节点不稳定），并确保调度器可以将 Pod 放置在具有足够容量的节点上。

利用 Init 容器进行设置

如果 Pod 在主应用程序启动之前需要依赖检查或数据设置（例如，等待数据库迁移完成），请使用 Init 容器。如果 Init 容器失败，Pod 将反复重启它，从而将设置错误与应用程序运行时错误清晰地隔离开来。

实用的分类流程

当你值班时，使用可重复的路径：

检查 kubectl get pods -n <namespace> -o wide，以便查看状态、重启次数、运行时间和节点位置。
运行 kubectl describe pod 并阅读 Events、State、Last State、挂载和资源设置。
使用 kubectl logs 拉取日志，对于已重启的容器添加 --previous，对于多容器 Pod 添加 -c。
如果 Pod 处于 Pending 状态，在阅读应用日志之前检查调度、污点、节点标签和 PVC。
如果 Pod 处于 Running 状态但未接收流量，检查就绪探针、Service 选择器和端点。
如果 Pod 被 OOMKilled，在简单地增加数值之前，将限制与实际内存图进行比较。

这个顺序可以防止你在 Kubernetes 甚至还没有启动应用程序时就直接跳到应用程序。

最终检查

最有用的习惯是将症状与原因分开。CrashLoopBackOff 是一个症状。原因可能是缺少密钥、错误的迁移、存活探针或内存限制。Pending 是一个症状。原因可能是 CPU 请求、PVC、污点或节点选择器。让 Pod 状态告诉你该看哪里，然后让事件和日志告诉你发生了什么变化。

Kubernetes Pod 故障排查：全面指南

Pod 诊断的三大支柱

1. 初始状态检查 (kubectl get pods)

解读 Pod 状态

2. 深度检查 (kubectl describe pod)

3. 查看日志 (kubectl logs)

常见的 Pod 故障场景及解决方案

场景 1：CrashLoopBackOff

场景 2：ImagePullBackOff / ErrImagePull

场景 3：Pending 状态（卡住）

场景 4：OOMKilled（因内存不足被杀死）

场景 5：CreateContainerConfigError 和 CreateContainerError

场景 6：运行但未就绪

预防未来故障：最佳实践

使用存活和就绪探针

强制资源限制和请求

利用 Init 容器进行设置

实用的分类流程

最终检查

1. 初始状态检查 (`kubectl get pods`)

2. 深度检查 (`kubectl describe pod`)

3. 查看日志 (`kubectl logs`)