kubectl 常用命令排查 Pod 问题

前言

在 Kubernetes 集群中，Pod 是最小的调度单元，也是应用运行的载体。当 Pod 出现异常时，快速定位问题至关重要。kubectl 是管理集群的核心命令行工具，熟练掌握其排查命令能大幅缩短故障恢复时间。本文将从基础状态查看入手，逐步深入到日志、事件、交互式调试与资源限制分析，提供一套系统化的 Pod 问题排查路径。

查看 Pod 状态与列表

列出 Pod

kubectl get pods

默认仅显示当前命名空间下的 Pod。常用扩展选项：

• -n <namespace> 查看指定命名空间。
• --all-namespaces 或 -A 查看所有命名空间。
• -o wide 显示更多列，包括节点 IP 和 Pod IP。
• --field-selector 按字段过滤，如 status.phase=Running。
• -l app=nginx 按标签过滤。

查看 Pod 详细状态

kubectl describe pod <pod-name>

输出包括 Pod 配置、当前状态、最近事件、容器状态及挂载卷等。重点关注 Events 部分，它会记录调度失败、镜像拉取错误、探针失败等关键信息。

检查 Pod 的当前阶段

kubectl get pod <pod-name> -o jsonpath='{.status.phase}'

常见阶段：Pending、Running、Succeeded、Failed、Unknown。结合容器状态可以更精确判断。

检查容器状态与重启原因

查看容器状态摘要

kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[*]}'

关注每个容器的 state：running、waiting、terminated。若处于 waiting，检查 reason 字段（如 CrashLoopBackOff、ImagePullBackOff）。重启次数可通过以下命令查看：

kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[*].restartCount}'

查看上一次终止容器的退出码与原因

kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[*].lastState}'

退出码 137 通常表示 OOMKilled，1 或 2 可能是应用自身错误。

获取 Pod 日志

查看实时日志

kubectl logs <pod-name> [container-name]

• -f 实时跟踪（类似 tail -f）。
• --tail=50 只显示最后 50 行。
• --since=5m 显示最近 5 分钟的日志。
• --previous / -p 查看上一个终止容器的日志，排查 CrashLoopBackOff 场景非常有用。
• 多容器 Pod 必须指定 -c <container-name>。

查看特定标签集合的日志

kubectl logs -l app=nginx --all-containers=true

在 Pod 内执行命令

进入容器 Shell

kubectl exec -it <pod-name> -- /bin/sh

如果 Pod 内不含 shell，可尝试 -- /bin/bash 或 -- /bin/sh。可加 -c <container-name> 指定容器。

运行一次性命令

kubectl exec <pod-name> -- ls /data

• -- 之后的参数会被原样传递给容器。
• 用于检查文件系统、网络连通性（如 ping、curl）、环境变量等。

拷贝文件（用于诊断）

kubectl cp <pod-name>:/path/to/file ./local-file

从 Pod 拷贝出来，便于进一步分析。

排查网络与服务连通性

测试 Pod 内部网络

进入 Pod 后执行：

curl -v http://<service-name>:<port>
nslookup <service-name>
ping <other-pod-ip>

检查 DNS 解析、Service 可达性。

使用临时调试 Pod

当目标 Pod 缺少工具时，可启动一个带工具的临时 Pod：

kubectl run tmp-shell --rm -i --tty --image=nicolaka/netshoot -- /bin/bash

这是网络排错利器，内置 curl、dig、tcpdump、iperf 等。

检查 Service 与 Endpoint

kubectl get svc
kubectl get endpoints <svc-name>

确保 Endpoint 非空，且 IP 就是目标 Pod 的 IP。

检查资源使用与限制

实时资源监控（需 Metrics Server）

kubectl top pod <pod-name>
kubectl top pod -l app=nginx --containers

观察 CPU 和内存使用是否接近 Limit，高内存使用可能导致 OOMKill。

查看资源配置

kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].resources}'

确认 requests/limits 设置是否合理，过低可能导致 CPU 节流或 OOM。

强制故障模拟与恢复

删除 Pod 强制重建

kubectl delete pod <pod-name>

若 Pod 由 Deployment/StatefulSet 管理，控制器会自动重建新 Pod，有助于清除瞬态故障。

强制替换 Pod（有时需结合 taint/toleration）

kubectl replace --force -f pod.yaml

但通常直接删除 Pod 更为简单。

给节点打污点隔离 Pod

kubectl taint node <node-name> key=value:NoExecute

已运行的 Pod 若不容忍污点将被驱逐，可观察重新调度过程。

分析事件与集群层面问题

查看整个命名空间的事件

kubectl get events -n <namespace> --sort-by='.lastTimestamp'
kubectl get events -A --field-selector involvedObject.name=<pod-name>

事件按时间排序，快速定位如镜像拉取失败、节点不可调度、挂载卷错误等。

检查节点状态

kubectl get nodes
kubectl describe node <node-name>

节点 NotReady 或资源压⼒（如 MemoryPressure、DiskPressure）会导致 Pod 无法运行或驱逐。

集群事件持久化

若事件丢失，查看 kubelet 或 kube-controller-manager 日志通常可获取更多信息，这需要登录节点或查看系统服务日志。

常见问题快速定位速查表

总结

排查 Pod 问题的核心思路是：状态 → 事件 → 日志 → 交互式诊断 → 网络与资源分析。kubectl 提供了一整套命令覆盖这些环节。建议初学者将常用命令保存为 alias 或使用 kubectl 插件（如 kubectl-debug、kubectl-watch）提升效率。遇到复杂故障时，按以上步骤系统化地收集信息，绝大多数 Pod 异常都能快速定位和修复。