故障排除：为什么我的 Kubernetes Pod 卡在 Pending 或 CrashLoopBackOff 状态？

当您等待部署时，Pending 和 CrashLoopBackOff 看起来相似，但它们意味着截然不同的事情。Pending 通常意味着 Kubernetes 无法放置或准备 Pod。CrashLoopBackOff 意味着容器确实启动了，然后退出了，并且 Kubernetes 正在延迟下一次重启。

这种区别很重要。一个挂起的 Pod 通常是调度器、镜像或存储问题。一个崩溃的 Pod 通常是应用程序、命令、探针、权限或内存问题。从这个区分开始，故障排除路径会大大缩短。

理解 Pod 状态：Pending 与 CrashLoopBackOff

在深入故障排除之前，理解这两种状态的含义至关重要。

Pod 状态：Pending

处于 Pending 状态的 Pod 意味着 Kubernetes 已经接受了 Pod 对象，但尚未完全进入运行中的容器状态。有时它还没有被调度到节点上。有时它已经分配了节点，但镜像拉取、卷挂载或沙箱设置尚未完成。

Pod 状态：CrashLoopBackOff

处于 CrashLoopBackOff 状态的 Pod 意味着 Pod 内的容器反复启动、崩溃然后重启。Kubernetes 在重启之间实施指数级回退延迟，以防止压垮节点。这种状态几乎总是指向容器内运行的应用程序或其直接环境的问题。

一个微妙的案例：如果工作负载本应是一个长时间运行的服务器，但容器以代码 0 退出，仍然可能进入重启循环。当 Deployment 错误地运行一次性命令时，经常发生这种情况，例如迁移脚本或立即完成的 shell 命令。

故障排除处于 Pending 状态的 Pod

当 Pod 处于 Pending 状态时，首先要查看的是调度器和它试图调度的节点。以下是常见原因和诊断步骤。

1. 节点资源不足

Pod 处于 Pending 状态的最常见原因之一是集群中没有节点拥有足够的可用资源（CPU、内存）来满足 Pod 的 requests。调度器找不到合适的节点。

诊断步骤：

1. 描述 Pod：kubectl describe pod 命令是您最好的朋友。它通常会显示事件，详细说明为什么 Pod 无法被调度。

   kubectl describe pod <pod-name> -n <namespace>
   

   查找类似 "FailedScheduling" 的事件以及诸如 "0/3 nodes are available: 3 Insufficient cpu" 或 "memory" 的消息。

2. 检查节点资源：查看节点的当前资源使用情况和容量。

   kubectl get nodes
   kubectl top nodes # (需要 metrics-server)
   

解决方案：

• 增加集群容量：向 Kubernetes 集群添加更多节点。
• 调整 Pod 资源请求：如果 Pod 清单中的 requests 设置过高，请减少 CPU 和内存的 requests。

  resources:
    requests:
      memory: "128Mi"
      cpu: "250m"
  

• 驱逐其他 Pod：手动从节点驱逐优先级较低的 Pod 以释放资源（谨慎使用）。

2. 镜像拉取错误

如果 Kubernetes 可以将 Pod 调度到节点，但节点无法拉取容器镜像，Pod 将保持 Pending 状态。

常见原因：

• 镜像名称/标签错误：镜像名称中的拼写错误或使用不存在的标签。
• 私有仓库认证：私有仓库缺少或错误的 ImagePullSecrets。
• 网络问题：节点无法访问镜像仓库。

诊断步骤：

1. 描述 Pod：同样，kubectl describe pod 是关键。查找类似 "Failed" 或 "ErrImagePull" 或 "ImagePullBackOff" 的事件。

   kubectl describe pod <pod-name> -n <namespace>
   

   示例输出事件：Failed to pull image "my-private-registry/my-app:v1.0": rpc error: code = Unknown desc = Error response from daemon: pull access denied for my-private-registry/my-app, repository does not exist or may require 'docker login'

2. 检查 ImagePullSecrets：验证 Pod 或 ServiceAccount 中是否正确配置了 imagePullSecrets。

   kubectl get secret <your-image-pull-secret> -o yaml -n <namespace>
   

解决方案：

• 更正镜像名称/标签：仔细检查部署清单中的镜像名称和标签。
• 配置 ImagePullSecrets：确保您已创建 docker-registry 密钥并将其链接到您的 Pod 或 ServiceAccount。

  kubectl create secret docker-registry my-registry-secret \n      --docker-server=your-registry.com \n      --docker-username=your-username \n      --docker-password=your-password \n      --docker-email=your-email -n <namespace>
  

  然后，将其添加到您的 Pod 规范中：

  spec:
    imagePullSecrets:
    - name: my-registry-secret
    containers:
    ...
  

• 网络连接：验证从节点到镜像仓库的网络连接。

如果您使用的是私有仓库，也请检查 ServiceAccount。许多团队将 imagePullSecrets 附加到命名空间的默认 ServiceAccount，而不是每个 Deployment：

kubectl get serviceaccount default -n <namespace> -o yaml

如果密钥存在但拉取仍然失败，请确认密钥中的仓库主机名与镜像引用中的主机名完全匹配。registry.example.com/app:v1 和 https://registry.example.com/app:v1 不是同一个引用。

3. 卷相关问题

如果您的 Pod 需要 PersistentVolumeClaim (PVC) 并且相应的 PersistentVolume (PV) 无法配置或绑定，Pod 将保持 Pending 状态。

诊断步骤：

1. 描述 Pod：查找与卷相关的事件。

   kubectl describe pod <pod-name> -n <namespace>
   

   事件可能显示 FailedAttachVolume、FailedMount 或类似消息。

2. 检查 PVC 和 PV 状态：检查 PVC 和 PV 的状态。

   kubectl get pvc <pvc-name> -n <namespace>
   kubectl get pv
   

   查找卡在 Pending 状态的 PVC 或未绑定的 PV。

解决方案：

• 确保 StorageClass：确保定义并可用 StorageClass，尤其是在使用动态配置时。
• 检查 PV 可用性：如果使用静态配置，请确保 PV 存在并匹配 PVC 条件。
• 验证访问模式：确保访问模式（例如 ReadWriteOnce、ReadWriteMany）兼容。

还要检查 Pod 是否调度在卷可以挂载的区域。在云集群中，在一个可用区创建的磁盘可能无法挂载到另一个可用区的节点。事件通常会提到卷节点亲和性或挂载失败。在这种情况下，修复方法可能是调度约束、不同的 StorageClass，或者在正确的区域重新创建卷。

4. 污点、容忍度和节点选择器

即使集群有足够的 CPU 和内存，Pod 也可能保持 Pending 状态。调度器还必须遵守放置规则。

常见示例：

• Pod 的 nodeSelector 不匹配任何节点。
• Pod 需要的节点亲和性过于严格。
• 唯一匹配的节点有污点，而 Pod 没有匹配的容忍度。
• 命名空间有配额阻止了请求的资源。

首先检查调度事件：

kubectl describe pod <pod-name> -n <namespace>

然后将 Pod 的放置规则与节点标签进行比较：

kubectl get pod <pod-name> -n <namespace> -o yaml
kubectl get nodes --show-labels
kubectl describe node <node-name>

如果事件说污点未被容忍，要么将 Pod 调度到其他地方，要么仅在负载确实属于那些节点时添加容忍度。不要盲目容忍每个污点。污点通常保护特殊节点、GPU 节点、基础设施节点或处于压力下的节点。

故障排除处于 CrashLoopBackOff 状态的 Pod

CrashLoopBackOff 状态表示应用程序级别的问题。容器成功启动但随后因错误退出，促使 Kubernetes 反复重启它。

1. 应用程序错误

最常见的原因是应用程序本身无法启动或在启动后不久遇到致命错误。

常见原因：

• 缺少依赖/配置：应用程序找不到关键的配置文件、环境变量或它依赖的外部服务。
• 命令/参数错误：容器规范中指定的 command 或 args 不正确或导致立即退出。
• 应用程序逻辑错误：导致应用程序在启动时崩溃的代码错误。

诊断步骤：

1. 查看 Pod 日志：这是最关键的一步。日志通常会显示导致应用程序崩溃的确切错误消息。

   kubectl logs <pod-name> -n <namespace>
   

   如果 Pod 反复崩溃，日志可能显示最近一次失败尝试的输出。要查看崩溃容器先前实例的日志，请使用 -p（previous）标志：

   kubectl logs <pod-name> -p -n <namespace>
   

2. 描述 Pod：在 Containers 部分查找 Restart Count，它指示容器崩溃的次数。另外，检查 Last State 的 Exit Code。

   kubectl describe pod <pod-name> -n <namespace>
   

   退出代码 0 通常意味着正常关闭，但任何非零退出代码都表示错误。常见的非零退出代码包括 1（一般错误）、137（SIGKILL，通常是 OOMKilled）、139（SIGSEGV，段错误）。

解决方案：

• 检查应用程序日志：根据日志，调试您的应用程序代码或配置。确保所有必需的环境变量、ConfigMap 和 Secret 都已正确挂载/注入。
• 本地测试：尝试使用相同的环境变量和命令在本地运行容器镜像，以重现和调试问题。

如果 Pod 有多个容器，请始终指定容器名称：

kubectl logs <pod-name> -c <container-name> -n <namespace>
kubectl logs <pod-name> -c <container-name> -p -n <namespace>

如果不使用 -c，您可能正在读取 sidecar 日志，而主应用程序才是崩溃的那个。

2. 存活性和就绪性探针失败

Kubernetes 使用存活性和就绪性探针来确定应用程序的健康状况和可用性。如果存活探针持续失败，Kubernetes 将重启容器，导致 CrashLoopBackOff。

诊断步骤：

1. 描述 Pod：在 Containers 部分检查 Liveness 和 Readiness 探针定义及其 Last State。

   kubectl describe pod <pod-name> -n <namespace>
   

   查找指示探针失败的消息，例如 "Liveness probe failed: HTTP probe failed with statuscode: 500"。

2. 检查应用程序日志：有时应用程序日志会提供探针端点为何失败的上下文。

解决方案：

• 调整探针配置：更正探针的 path、port、command、initialDelaySeconds、periodSeconds 或 failureThreshold。
• 确保探针端点健康：验证探针目标应用程序端点是否实际健康并按预期响应。应用程序可能启动时间过长，需要更大的 initialDelaySeconds。

对于启动缓慢的应用程序，请考虑使用 startupProbe。它为应用程序提供更多时间进行初始化，然后存活探针才开始判断。这比为每次重启设置巨大的存活 initialDelaySeconds 更简洁。

3. 资源限制超出

如果容器持续尝试使用超过其 memory.limit 的内存，或者由于超过其 cpu.limit 而受到 CPU 限制，内核可能会终止该进程，通常会出现 OOMKilled（Out Of Memory Killed）事件。

诊断步骤：

1. 描述 Pod：在 Last State 或 Events 部分查找 OOMKilled。退出代码 137 通常表示 OOMKilled 事件。

   kubectl describe pod <pod-name> -n <namespace>
   

2. 检查 kubectl top：如果安装了 metrics-server，请使用 kubectl top pod 查看 Pod 的实际资源使用情况。

   kubectl top pod <pod-name> -n <namespace>
   

解决方案：

• 增加资源限制：如果您的应用程序确实需要更多资源，请增加 Pod 清单中的 memory 和/或 cpu limits。这可能需要节点上有更多容量。

  resources:
    requests:
      memory: "256Mi"
      cpu: "500m"
    limits:
      memory: "512Mi" # 增加此项
      cpu: "1000m"   # 增加此项
  

• 优化应用程序：分析您的应用程序以识别并减少其资源消耗。

4. 权限问题

如果容器缺乏访问所需文件、目录或网络资源的必要权限，它们可能会崩溃。

诊断步骤：

1. 检查日志：应用程序日志可能显示权限拒绝错误（EACCES）。
2. 描述 Pod：检查正在使用的 ServiceAccount 以及任何挂载的 securityContext 设置。

解决方案：

• 调整 securityContext：根据需要设置 runAsUser、fsGroup 或 allowPrivilegeEscalation。
• ServiceAccount 权限：确保与 Pod 关联的 ServiceAccount 通过 RoleBinding 和 ClusterRoleBinding 绑定了必要的 Role 和 ClusterRole。
• 卷权限：确保挂载的卷（例如 emptyDir、hostPath、ConfigMap、Secret）对容器用户具有正确的权限。

快速决策树

当有人说“Pod 坏了”时，按顺序运行以下命令：

kubectl get pod <pod-name> -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --all-containers=true --tail=100
kubectl logs <pod-name> -n <namespace> --all-containers=true -p --tail=100

然后分支：

• 如果 kubectl get pod -o wide 中没有节点，则专注于调度：请求、污点、亲和性、配额和节点可用性。
• 如果有节点但事件提到镜像拉取，则专注于镜像名称、标签、仓库认证和节点到仓库的网络访问。
• 如果事件提到挂载或附加，则专注于 PVC、PV、StorageClass、访问模式和区域放置。
• 如果 Pod 启动然后重启，则专注于日志、退出代码、探针、命令/参数、配置、密钥和内存限制。

这个顺序避免了一个常见错误：读取从未实际启动应用程序容器的 Pod 的应用程序日志。

读取退出代码而不反应过度

退出代码是线索，而不是完整的解释。

• 1 通常意味着应用程序返回了一般错误。日志比数字更重要。
• 2 可能指向许多程序中的命令行使用错误。
• 126 通常意味着命令存在但无法执行。
• 127 通常意味着未找到命令。
• 137 常见于进程收到 SIGKILL 时；在 Kubernetes 中，这通常（但不总是）与 OOMKilled 相关。
• 143 意味着进程收到 SIGTERM，这可能在正常终止期间发生。

如果退出代码是 137，请在假设内存泄漏之前检查 Pod 的 Last State 和事件。节点排空、驱逐或手动终止也可能终止容器。

通用诊断步骤和工具

以下是遇到 Pod 问题时可以运行的命令快速检查清单：

• 快速概览：检查 Pod 的状态。

  kubectl get pods -n <namespace>
  kubectl get pods -n <namespace> -o wide
  

• 详细 Pod 信息：理解 Pod 事件、状态和条件的最关键命令。

  kubectl describe pod <pod-name> -n <namespace>
  

• 容器日志：查看您的应用程序报告了什么。

  kubectl logs <pod-name> -n <namespace>
  kubectl logs <pod-name> -p -n <namespace> # 先前实例
  kubectl logs <pod-name> -f -n <namespace> # 跟踪日志
  

• 集群范围事件：有时问题不在于特定 Pod，而在于集群范围的事件（例如节点压力）。

  kubectl get events -n <namespace>
  

• 交互式调试：如果您的容器启动但很快崩溃，您可能能够短暂地 exec 进入它，或者如果配置了单独的调试容器，则进入其中。

  kubectl exec -it <pod-name> -n <namespace> -- bash
  

  （注意：这仅在容器存活足够长时间以便附加时才有效。）

避免 Pod 问题的最佳实践

预防胜于治疗。遵循这些最佳实践可以显著减少 Pending 和 CrashLoopBackOff 事件：

• 设置现实的资源请求和限制：从合理的 requests 和 limits 开始，然后根据应用程序分析和监控进行微调。
• 使用特定的镜像标签：在生产中避免使用 latest 标签。使用不可变标签（例如 v1.2.3、commit-sha）以实现可重复性。
• 实施健壮的探针：配置准确反映应用程序健康状况的 liveness 和 readiness 探针。使用 initialDelaySeconds 考虑启动时间。
• 集中式日志记录和监控：使用 Prometheus、Grafana、ELK 堆栈或云原生日志服务等工具来收集和分析 Pod 日志和指标。
• 清单的版本控制：将您的 Kubernetes 清单存储在版本控制系统（例如 Git）中，以跟踪更改并促进回滚。
• 彻底测试：在部署到生产环境之前，在开发和暂存环境中测试您的容器镜像和 Kubernetes 部署。
• 优雅关闭：确保您的应用程序处理 SIGTERM 信号以进行优雅关闭，允许它们在终止前释放资源。

什么通常能最快修复问题

对于 Pending，kubectl describe pod 通常是最快的路径，因为调度器和 kubelet 事件解释了 Kubernetes 无法做什么。对于 CrashLoopBackOff，先前的日志通常是最快的路径，因为当前容器可能太新，无法显示导致循环的崩溃。

在修复直接问题后，寻找预防步骤：适当大小的请求、更好的镜像标签、启动探针、CI 中缺失的密钥检查或更清晰的运行手册。最好的 Pod 事件是下次更容易识别的事件。