掌握 kubectl logs 和 describe，实现高效 Pod 调试

掌握 `kubectl logs` 和 `describe` 以实现高效的 Pod 调试

在像 Kubernetes 这样的分布式环境中调试应用程序可能很困难。当一个 Pod 无法启动、进入重启循环或表现出意外行为时，Kubernetes 运维人员工具箱中最重要的两个工具是 kubectl describe 和 kubectl logs。

这两个命令提供了关于 Kubernetes Pod 状态和历史的不同但互补的视图。kubectl describe 提供 Pod 的元数据、状态、环境变量以及至关重要的系统事件历史记录。kubectl logs 提供容器化应用程序本身生成的标准输出 (stdout) 和标准错误 (stderr) 流。

掌握与这些命令相关的标志和技术对于快速诊断和解决问题至关重要，可以显著提高您的整体集群故障排除效率。

三步 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

输出中的关键部分

查看 describe 的输出时，请关注以下关键部分：

A. 状态和状况

查看顶部的 Status 字段，然后查看 Pod 内各个容器的状态。这会告诉您容器是 Running（运行中）、Waiting（等待中）还是 Terminated（已终止），并提供该状态的原因。

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

B. 容器配置

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

C. `Events` 部分（关键）

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

Events 显示的常见错误：

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

提示： 如果 Events 部分干净，问题通常与应用程序相关（运行时崩溃、初始化失败、配置错误），这会引导您接下来使用 kubectl logs。

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

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

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

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

假设一个 Pod 卡在 Running 状态，但偶尔会重启，导致中断。

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

kubectl describe pod web-server-dpl-abc

输出在 Events 部分显示：

类型     原因      年龄   来自               消息
----     ------      ----  ----               -------
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 因存活探针失败而重启，而探针失败是因为应用程序无法连接到数据库。问题出在外部网络或数据库配置上，而不是容器本身。

最佳实践和警告

实践	命令	原理
始终检查先前日志	`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 describe 和 kubectl logs 是 Kubernetes 调试中不可或缺的核心命令。通过将 describe 视为系统状态报告（关注配置、事件和调度错误），将 logs 视为应用程序执行流（关注代码错误和运行时行为），您可以系统地缩小几乎任何 Pod 故障的原因范围，从而显著减少集群中的平均解决时间 (MTTR)。

掌握 kubectl logs 和 describe 以实现高效的 Pod 调试