4. 故障排查基础命令：kubectl describe、kubectl logs、kubectl exec、kubectl get events 的实战用法

在 Kubernetes 集群故障排查中，kubectl 是最核心的 CLI 工具。本章聚焦四个最常用的诊断命令：describe、logs、exec 和 get events。掌握这些命令的实战用法，能够覆盖 80% 以上的日常故障场景，为后续自动化回滚策略的触发与集成打下坚实基础。

4.1 命令功能对比与适用场景

四个命令分别从不同维度提供故障信息，下表总结了它们的核心用途与典型场景：

命令 核心功能 典型故障场景 输出特点
kubectl describe 查看资源的详细状态、事件、元数据 Pod 启动失败、资源绑定异常、配置错误 结构化文本，包含状态机、条件、关联事件
kubectl logs 获取容器标准输出/错误日志 应用崩溃、业务逻辑错误、启动阻塞 原始日志流，支持时间戳与多容器选择
kubectl exec 在运行中的容器内执行命令 网络连通性验证、文件系统检查、进程状态 交互式或单次命令输出
kubectl get events 展示集群中按时间排序的事件流 节点异常、驱逐、调度失败、OOM 表格形式，包含类型、原因、时间、对象
实战建议：排查故障时，建议按 get events → describe → logs → exec 的顺序逐步深入。先看全局事件，再查资源详情，最后进入容器内部诊断。

4.2 kubectl describe —— 资源状态全景图

kubectl describe 是获取资源完整状态的首选命令。它聚合了资源的当前状态、标签、注解、关联对象以及最近的事件列表，是定位配置错误和状态异常的关键工具。

4.2.1 常用语法与参数

# 查看 Pod 详情
kubectl describe pod <pod-name> -n <namespace>

# 查看 Deployment 详情
kubectl describe deployment <deploy-name> -n <namespace>

# 查看 Node 详情（包含资源容量与条件）
kubectl describe node <node-name>

# 查看 Service 详情（包含 Endpoint 信息）
kubectl describe svc <service-name> -n <namespace>

4.2.2 关键输出字段解读

以 kubectl describe pod 为例，以下字段是排查重点：

  • Conditions：Pod 的状态条件列表，如 PodScheduled、Initialized、ContainersReady、Ready。每个条件包含 Status（True/False/Unknown）、LastTransitionTime 和 Reason。
  • Events：与 Pod 相关的最近事件，按时间倒序排列。重点关注 Warning 类型的事件，如 FailedScheduling、BackOff、FailedMount。
  • Containers.State：容器的当前状态（Waiting/Running/Terminated）。Waiting 状态通常伴随 Reason 字段，如 CrashLoopBackOff、ImagePullBackOff。
  • Volumes：挂载卷的详细信息，包括 ClaimName、MountPath 和 ReadOnly 标志。
故障排查案例：当 Pod 处于 Pending 状态时，执行 kubectl describe pod <pod-name>。如果 Events 中出现 FailedScheduling 且 Reason 为 Insufficient cpu，说明节点资源不足，需要扩容节点或调整资源请求。

4.3 kubectl logs —— 应用日志的精准捕获

kubectl logs 用于获取容器内应用的标准输出（stdout）和标准错误（stderr）日志。对于多容器 Pod，必须指定容器名称。

4.3.1 常用语法与参数

# 查看单容器 Pod 日志
kubectl logs <pod-name> -n <namespace>

# 查看多容器 Pod 中指定容器的日志
kubectl logs <pod-name> -c <container-name> -n <namespace>

# 实时跟踪日志流（类似 tail -f）
kubectl logs -f <pod-name> -n <namespace>

# 查看最近 100 行日志
kubectl logs --tail=100 <pod-name> -n <namespace>

# 显示带时间戳的日志
kubectl logs --timestamps <pod-name> -n <namespace>

# 查看前一个实例的日志（容器重启后使用）
kubectl logs --previous <pod-name> -c <container-name> -n <namespace>

4.3.2 实战技巧

  • CrashLoopBackOff 场景：使用 --previous 参数查看崩溃前容器的最后日志，通常能捕获到异常堆栈。
  • 多容器 Pod：Sidecar 容器（如 Istio Proxy）的日志可能包含网络层面的错误，不要遗漏。
  • 日志量过大：结合 --tail 和 --since（如 --since=5m）限制输出范围，避免终端卡顿。
注意：kubectl logs 只能获取容器内进程写入 stdout/stderr 的日志。如果应用将日志写入文件而非标准输出，需要使用 kubectl exec 进入容器查看文件。

4.4 kubectl exec —— 容器内诊断的瑞士军刀

当需要深入容器内部进行诊断时，kubectl exec 提供了类似 SSH 的能力，但无需管理 SSH 密钥。

4.4.1 常用语法与参数

# 在容器内执行单条命令
kubectl exec <pod-name> -n <namespace> -- <command>

# 在指定容器内执行命令（多容器 Pod）
kubectl exec <pod-name> -c <container-name> -n <namespace> -- <command>

# 启动交互式 Shell
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh

# 使用 bash（如果容器内安装了 bash）
kubectl exec -it <pod-name> -n <namespace> -- /bin/bash

4.4.2 典型诊断命令

诊断目标 执行命令 说明
网络连通性 curl -v http://service-name:port 测试服务间 HTTP 调用是否正常
DNS 解析 nslookup service-name.namespace.svc.cluster.local 验证集群 DNS 是否正常工作
进程状态 ps aux 查看容器内运行的进程列表
文件系统 ls -la /path/to/mount 检查挂载卷内容是否正常
环境变量 env 验证配置是否通过环境变量正确注入
安全提示：生产环境中，建议使用 kubectl exec 的审计日志功能，记录所有 exec 操作。同时，容器镜像应最小化，避免安装不必要的调试工具。

4.5 kubectl get events —— 集群事件的时序分析

kubectl get events 提供了集群中所有资源对象的事件流，是发现异常行为的第一道防线。事件按时间排序，包含类型（Normal/Warning）、原因、来源对象和详细消息。

4.5.1 常用语法与参数

# 查看所有命名空间的事件
kubectl get events --all-namespaces

# 查看指定命名空间的事件
kubectl get events -n <namespace>

# 按时间排序（最新在前）
kubectl get events --sort-by='.lastTimestamp' -n <namespace>

# 只查看 Warning 类型事件
kubectl get events --field-selector type=Warning -n <namespace>

# 查看与特定 Pod 相关的事件
kubectl get events --field-selector involvedObject.name=<pod-name> -n <namespace>

# 持续监控事件流
kubectl get events -w -n <namespace>

4.5.2 事件字段解读

  • LAST SEEN：事件最近一次发生的时间。
  • TYPE：事件类型，Normal 表示正常操作，Warning 表示异常。
  • REASON：事件原因，如 FailedScheduling、BackOff、NodeNotReady。
  • OBJECT：事件关联的资源对象，格式为 kind/name。
  • MESSAGE：详细描述，包含错误码、资源名称等关键信息。
故障排查案例：当 Pod 频繁重启时，执行 kubectl get events --field-selector type=Warning -n <namespace> | grep <pod-name>。如果看到 BackOff 事件且 Reason 为 CrashLoopBackOff，说明容器启动后立即崩溃，需要结合 kubectl logs --previous 查看崩溃日志。

4.6 四命令协同排查流程图

下图展示了四个命令在故障排查流程中的协同关系，从事件发现到容器内诊断的完整链路：

kubectl 故障排查四命令协同流程 故障现象出现 步骤 1：kubectl get events 全局事件扫描，定位异常对象 步骤 2：kubectl describe 查看资源详情、状态、条件与事件 应用异常？ 是 步骤 3a：kubectl logs 查看应用日志，定位错误堆栈 否 步骤 3b：kubectl exec 进入容器，检查环境/网络/进程 定位根因，制定修复方案

4.7 实战案例：Pod CrashLoopBackOff 排查

以下是一个完整的排查案例，展示四个命令如何串联使用：

  1. 发现异常：kubectl get pods -n production 显示 web-app-7d8f9c6b4-abcde 处于 CrashLoopBackOff 状态。
  2. 查看事件：kubectl get events --field-selector involvedObject.name=web-app-7d8f9c6b4-abcde -n production，确认事件类型为 Warning，Reason 为 BackOff。
  3. 查看详情：kubectl describe pod web-app-7d8f9c6b4-abcde -n production，在 Containers.State 中看到 Waiting: CrashLoopBackOff，Events 中显示 Started container 后立即 BackOff。
  4. 查看日志：kubectl logs --previous web-app-7d8f9c6b4-abcde -n production，输出显示 Error: listen tcp :8080: bind: address already in use。
  5. 进入容器验证：kubectl exec -it web-app-7d8f9c6b4-abcde -n production -- /bin/sh，执行 netstat -tlnp | grep 8080，确认端口被旧进程占用。
  6. 根因：应用启动脚本未正确处理旧进程，导致端口冲突。修复后重新部署。
自动化集成提示：在回滚策略自动化中，可以通过脚本定期执行 kubectl get events --field-selector type=Warning，当检测到 CrashLoopBackOff 或 FailedScheduling 等关键事件时，自动触发回滚流程。

4.8 命令输出对比表

下表总结了四个命令的输出格式与信息密度，帮助你在不同场景下快速选择：

命令 输出格式 信息密度 适合快速扫描 适合深度分析
kubectl get events 表格 中 ✅ ❌
kubectl describe 结构化文本 高 ❌ ✅
kubectl logs 原始文本流 中 ✅ ✅
kubectl exec 命令输出 可变 ❌ ✅
← 上一章 📖 返回目录 下一章 →