精通 kubectl logs 和 describe，高效调试 Pod

当 Kubernetes Pod 失败时，kubectl describe 和 kubectl logs 通常会告诉你下一步该看哪里。describe 解释 Kubernetes 尝试做了什么。logs 显示容器在失败之前、期间或之后写入了什么。

这些命令提供了对 Kubernetes Pod 状态和历史的不同但互补的视图。kubectl describe 提供 Pod 的元数据、状态、环境变量，以及关键的系统事件历史。kubectl logs 提供容器化应用程序本身生成的标准输出（stdout）和标准错误（stderr）流。

诀窍在于以正确的顺序使用它们。如果 Pod 从未被调度，日志将无济于事。如果 Pod 启动并退出，事件可能只告诉你它崩溃了；应用程序日志通常解释原因。

三步 Pod 调试工作流程

在深入命令之前，了解典型的调试工作流程会有所帮助：

检查状态： 使用 kubectl get pods 识别失败状态（Pending、CrashLoopBackOff、ImagePullBackOff 等）。
获取上下文和事件： 使用 kubectl describe pod 了解为什么发生状态转换（例如，调度器失败、存活探针失败、卷挂载失败）。
检查应用程序输出： 使用 kubectl logs 检查应用程序的运行时行为（例如，配置错误、数据库连接失败、堆栈跟踪）。

1. `kubectl describe`：系统分类工具

当 Pod 行为异常时，kubectl describe 是您应该运行的第一个命令。它不显示应用程序输出，但提供 Kubernetes 本身记录的关于 Pod 的关键元数据和历史。

基本用法

基本用法只需要 Pod 名称：

kubectl describe pod my-failing-app-xyz789

当您不在默认命名空间时，显式使用命名空间：

kubectl describe pod my-failing-app-xyz789 -n payments

如果您只知道部署或标签，请先找到 Pod：

kubectl get pods -n payments -l app=checkout -o wide

输出中的关键部分

在查看 describe 的输出时，关注这些关键部分：

A. 状态和状态

查看顶部的 Status 字段，然后查看 Pod 内各个容器的状态。这告诉您容器是 Running、Waiting 还是 Terminated，并提供该状态的原因。

字段	常见状态/原因	含义
`Status`	`Pending`	Pod 正在等待调度或缺少资源。
`Reason`	`ContainerCreating`	容器运行时正在拉取镜像或运行设置。
`State`	`Waiting` / `Reason: CrashLoopBackOff`	容器启动并反复退出。
`State`	`Terminated` / `Exit Code`	容器完成执行。非零退出代码通常表示错误。

B. 容器配置

此部分验证您的环境变量、资源请求/限制、卷挂载以及存活/就绪探针是否正确定义，与您应用的清单匹配。

C. `Events` 部分（关键）

位于输出底部的 Events 部分可以说是最有价值的部分。它提供了 Kubernetes 控制平面为 Pod 所做操作的按时间顺序的日志，包括警告和错误。

Events 揭示的常见错误：

调度问题： Warning FailedScheduling：表示调度器找不到合适的节点（例如，由于资源限制、节点污点或亲和性规则）。
镜像拉取失败： Warning Failed: ImagePullBackOff：表示镜像名称错误、标签不存在，或者 Kubernetes 缺少从私有仓库拉取的凭据。
卷错误： Warning FailedAttachVolume：表示连接外部存储的问题。

提示： 如果 Events 部分干净且容器已启动，则问题通常与应用程序相关：环境变量错误、迁移失败、缺少密钥、无法访问的依赖项或立即退出的进程。

2. `kubectl logs`：检查应用程序输出

如果 describe 显示 Pod 已成功调度并且容器尝试运行，下一步是使用 kubectl logs 检查标准输出流。

基本日志检索和实时流式传输

要查看 Pod 中主容器的当前日志：

# 检索截至当前时刻的所有日志
kubectl logs my-failing-app-xyz789

# 实时流式传输日志（用于监控启动）
kubectl logs -f my-failing-app-xyz789

处理多容器 Pod

对于使用 Sidecar 模式或其他多容器设计的 Pod，您必须使用 -c 或 --container 标志指定要查看哪个容器的日志。

# 查看 Pod 内 'sidecar-proxy' 容器的日志
kubectl logs my-multi-container-pod -c sidecar-proxy

# 流式传输主应用程序容器的日志
kubectl logs -f my-multi-container-pod -c main-app

调试重启容器（`--previous`）

最常见的调试场景之一是 CrashLoopBackOff 状态。当容器重启时，kubectl logs 只显示当前（失败）尝试的输出，这通常只包含崩溃前的启动消息。

要查看前一个终止实例的日志——其中包含导致退出的实际错误——请使用 --previous 标志（-p）：

# 查看前一个崩溃容器实例的日志
kubectl logs my-crashloop-pod --previous

# 如果需要，与容器规范结合使用
kubectl logs my-crashloop-pod -c worker --previous

限制输出

对于高容量日志，检索整个历史可能很慢或难以处理。使用 --tail 将输出限制为最后 N 行。

# 仅显示容器日志的最后 50 行
kubectl logs my-high-traffic-app --tail=50

您还可以添加时间戳和时间窗口：

kubectl logs my-high-traffic-app --tail=100 --timestamps
kubectl logs my-high-traffic-app --since=10m

对于部署，最近的 kubectl 版本可以通过工作负载名称获取日志：

kubectl logs deploy/checkout-api -n payments --tail=100

当范围太广时，使用标签选择器：

kubectl logs -n payments -l app=checkout --all-containers=true --tail=50

3. 结合技术进行高级诊断

有效的调试通常涉及在 describe 和特定的 logs 命令之间快速切换。

案例研究：诊断存活探针失败

想象一个 Pod 卡在 Running 状态但偶尔重启，导致中断。

第 1 步：检查 describe 以获取系统视图。

kubectl describe pod web-server-dpl-abc

输出在 Events 部分显示：

Type     Reason      Age   From               Message
----     ------      ----  ----               -------
Warning  Unhealthy   2s    kubelet, node-a01  Liveness probe failed: HTTP GET http://10.42.0.5:8080/health failed: 503 Service Unavailable

第 1 步的结论： 容器正在运行，但存活探针失败并返回 503 错误，导致 Kubernetes 重启容器。

第 2 步：检查 logs 以获取应用程序上下文。

现在，调查为什么应用程序返回 503 状态，这是一个应用程序级别的失败。

kubectl logs web-server-dpl-abc --tail=200

日志输出显示：

2023-10-26 14:01:15 ERROR Database connection failure: Timeout connecting to DB instance 192.168.1.10

最终结论： Pod 因存活探针失败而重启，而探针失败是因为应用程序无法连接到数据库。问题是外部网络或数据库配置，而不是容器本身。

案例研究：无日志的 Pending Pod

处于 Pending 状态的 Pod 通常没有有用的容器日志，因为还没有容器启动。

kubectl get pod report-worker-6f9c7b9b7d-f2q8m -n analytics

输出：

NAME                                  READY   STATUS    RESTARTS   AGE
report-worker-6f9c7b9b7d-f2q8m        0/1     Pending   0          4m

直接使用 describe：

kubectl describe pod report-worker-6f9c7b9b7d-f2q8m -n analytics

事件可能显示：

Warning  FailedScheduling  default-scheduler  0/6 nodes are available: 6 Insufficient memory.

这不是应用程序错误。Pod 请求的内存超过了调度器可以放置的数量。下一步是检查部署请求、集群容量、节点污点和自动缩放器行为：

kubectl get deploy report-worker -n analytics -o yaml
kubectl top nodes

案例研究：ImagePullBackOff

对于 ImagePullBackOff，日志通常是空的，因为容器镜像从未启动。describe 提供有用的错误：

kubectl describe pod api-7dfb9c8b7f-bd2p9 -n staging

常见的事件消息包括不存在的镜像标签、针对私有仓库的身份验证失败，或到达仓库的 DNS/网络问题。修复可能就像更正标签一样简单：

kubectl set image deploy/api api=registry.example.com/api:2026-05-24 -n staging

或者可能需要检查镜像拉取密钥：

kubectl get secret regcred -n staging
kubectl describe serviceaccount default -n staging

案例研究：带有静默应用程序的多容器 Pod

如果您查看错误的容器，Sidecar 可能会隐藏信号。首先列出容器名称：

kubectl get pod checkout-84f7c9d7bf-px5mx -n payments \
  -o jsonpath='{.spec.containers[*].name}{"\n"}'

然后仔细检查每个容器：

kubectl logs checkout-84f7c9d7bf-px5mx -n payments -c checkout --tail=100
kubectl logs checkout-84f7c9d7bf-px5mx -n payments -c envoy --tail=100

如果应用程序日志安静，但代理日志显示上游连接失败，则 Pod 从 Kubernetes 的角度来看可能是健康的，但流量仍然通过服务网格或代理配置失败。

最佳实践和警告

实践	命令	理由
始终检查以前的日志	`kubectl logs --previous`	诊断 `CrashLoopBackOff` 所必需。关键错误几乎总是在前一次运行中。
指定容器	`kubectl logs -c <name>`	避免多容器 Pod 中的歧义，并防止从意外的 sidecar 获取日志。
对批量操作使用标签	`kubectl logs -l app=frontend -f`	允许同时从匹配选择器的多个 Pod 流式传输日志（对滚动更新有用）。
警告：日志轮换	N/A	Kubernetes 节点执行日志轮换。早于节点配置的保留策略（通常是几天或基于大小）的日志将被修剪，并且无法通过 `kubectl logs` 使用。对于长期保留，请使用外部集中式日志记录解决方案（例如，Fluentd、Loki、Elastic Stack）。

这些命令无法告诉您的事情

kubectl logs 仅显示节点保留的容器 stdout 和 stderr。如果应用程序写入容器内的文件，kubectl logs 可能什么也不显示。这是日志记录设计问题，而不是 kubectl 问题。

kubectl describe 显示 Kubernetes 对象状态和最近事件，但事件不是永久审计日志。旧事件会过期。对于长期调查，将相关输出复制到事件记录中。

这两个命令都不能替代指标。Pod 可能正在运行并正常记录日志，而 CPU 限制、内存压力或下游延迟导致用户可见的问题。在 describe 和 logs 之后，接下来的命令通常是：

kubectl top pod -n payments
kubectl top node
kubectl get events -n payments --sort-by=.lastTimestamp

当 Kubernetes 无法创建或保持 Pod 运行时，首先使用 describe。当 Pod 正在运行但应用程序行为异常时，首先使用 logs。在它们之间切换，直到您能将平台症状与应用程序症状分开。

您可以重复使用的调试流程

当您处于压力之下时，每次都使用相同的流程：

kubectl get pod <pod> -n <namespace> -o wide
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --all-containers=true --tail=100
kubectl logs <pod> -n <namespace> --all-containers=true --previous --tail=100
kubectl get events -n <namespace> --sort-by=.lastTimestamp

顺序很重要。get pod -o wide 告诉您节点、Pod IP、重启次数和年龄。describe 告诉您调度、镜像、卷、探针和容器状态详细信息。当前日志显示正在运行的容器现在在做什么。以前的日志捕获已经发生的崩溃。事件显示相同的问题是否在整个命名空间中发生。

对于部署，添加回滚检查：

kubectl rollout status deploy/<name> -n <namespace>
kubectl describe deploy/<name> -n <namespace>
kubectl get rs -n <namespace> -l app=<label>

有时您正在调试的 Pod 来自滚动更新期间的旧 ReplicaSet。如果您修复了部署但继续从旧的终止 Pod 读取日志，您可能会花半小时追逐错误的问题。

正确解读重启次数

RESTARTS 列是线索，而不是诊断。节点耗尽后的重启次数为 1 可能无害。每分钟增加的重启次数是实时故障。使用 describe 检查最后状态：

Last State:     Terminated
  Reason:       Error
  Exit Code:    1
  Started:      Sun, 24 May 2026 10:14:02 +0800
  Finished:     Sun, 24 May 2026 10:14:07 +0800

退出代码 1 通常意味着进程因一般应用程序错误而退出。137 通常意味着进程被杀死，通常是因为超过了内存限制，但您应该通过 Reason 字段和节点/容器运行时上下文来确认。143 通常出现在进程在正常终止期间收到 SIGTERM 时。不要将每个非零退出代码都视为相同类型的失败。

当怀疑内存时，查找：

Reason:       OOMKilled
Exit Code:    137

然后比较容器限制与实际使用情况：

kubectl describe pod <pod> -n <namespace> | rg -A5 'Limits|Requests'
kubectl top pod <pod> -n <namespace>

如果未安装 metrics-server，kubectl top 将无法工作。在这种情况下，请使用平台的指标系统或节点级工具。