容器与云原生 / 系统课时
调试运行中的 Pod
调试运行中的 Pod
Pod 运行异常时,最有效的做法不是直接重启,而是按“状态与事件 → 日志 → 容器内部 → 网络入口 → 临时调试容器”的顺序收集证据。本节给出一套可复制的命令路径,帮助你判断问题究竟来自调度、启动、应用进程还是网络访问。
学习目标
- 能使用
describe、Events 和logs快速锁定 Pod 的异常阶段 - 能用
exec与port-forward验证容器内部状态和应用端口 - 能在业务镜像没有 Shell 或诊断工具时使用临时调试容器
先判断问题落在哪一层
先获取 Pod 的当前状态,再看 describe 中的 Conditions、容器状态和 Events。Pending 常指向调度、镜像拉取或卷挂载;CrashLoopBackOff 说明容器反复退出;Running 但业务不可用,则应继续检查应用日志、进程和端口。

下面的命令把命名空间和 Pod 名写成占位符,执行前替换为实际值。
kubectl get pod -n <NAMESPACE> <POD> -o wide
kubectl describe pod -n <NAMESPACE> <POD>
kubectl get events -n <NAMESPACE> --field-selector involvedObject.name=<POD> --sort-by='.lastTimestamp'预期结果
NAME READY STATUS RESTARTS AGE IP NODE
<POD> <VALUE> <VALUE> <VALUE> <TIME> <IP> <VALUE>
Name: <POD>
Namespace: <NAMESPACE>
Status: <VALUE>
Containers:
<CONTAINER>:
State: <VALUE>
Conditions:
<VALUE>
Events:
<VALUE>
LAST SEEN TYPE REASON OBJECT MESSAGE
<TIME> <VALUE> <VALUE> pod/<POD> <VALUE>实际字段和值会因故障类型而不同。重点不是背输出,而是确认异常发生在调度前、容器启动时,还是容器已经运行之后。
用日志确认应用是否启动成功
容器有标准输出时,logs 通常是定位应用启动失败最快的入口。对于反复重启的容器,当前日志可能只包含新一轮启动内容,此时要读取上一轮已终止容器的日志。
kubectl logs -n <NAMESPACE> <POD> -c <CONTAINER> --tail=100
kubectl logs -n <NAMESPACE> <POD> -c <CONTAINER> --previous --tail=100预期结果
<VALUE>第一条返回当前容器最近 100 行日志;第二条仅在该容器存在上一轮终止实例时有效。若返回 previous terminated container ... not found,说明没有可读取的上一轮日志,应回到 describe 查看退出原因和重启计数。
进入容器检查运行环境
当 Pod 处于 Running,但应用行为异常,可以使用 exec 在容器内部执行诊断命令。业务镜像必须包含对应的 Shell 和工具;distroless 镜像通常不满足这个条件。
kubectl exec -n <NAMESPACE> <POD> -c <CONTAINER> -- sh -c 'id; echo "hostname=$(hostname)"; echo resolv.conf:; head -n 3 /etc/resolv.conf'预期结果
uid=<ID>(<VALUE>) gid=<ID>(<VALUE>) groups=<VALUE>
hostname=<VALUE>
resolv.conf:
<VALUE>
<VALUE>
<VALUE>这里检查的是“命令能否进入目标容器、容器身份是否符合预期、基础 DNS 配置文件是否存在”。若 sh 本身不存在,不要把它误判成 Pod 故障,应改用临时调试容器。
用端口转发隔离网络链路
port-forward 可以把本机端口直接转发到 Pod 端口,适合区分“应用自身没有监听”和“Service、Ingress 或外部网络链路有问题”。它不经过 Service 负载均衡,因此只能作为诊断手段。
kubectl port-forward -n <NAMESPACE> pod/<POD> 18080:<PORT>预期结果
Forwarding from 127.0.0.1:18080 -> <PORT>
Forwarding from [::1]:18080 -> <PORT>保持该命令运行,再在另一个终端访问应用实际存在的路径。
curl -i http://127.0.0.1:18080/<PATH>预期结果
HTTP/1.1 <VALUE>
<VALUE>如果端口转发建立成功,但访问时提示连接被拒绝,优先检查容器是否真正监听 <PORT>。如果直接访问 Pod 正常而通过 Service 或 Ingress 失败,再转向检查选择器、Endpoint、NetworkPolicy 和入口配置。
业务镜像没有工具时使用临时调试容器
临时调试容器可以附加到已经运行的 Pod,而不需要重建业务镜像。它适合处理 distroless 镜像、缺少 Shell 或缺少网络工具的场景。
kubectl debug -n <NAMESPACE> -it <POD> --image=busybox:1.36 --target=<CONTAINER> -- sh预期结果
Targeting container "<CONTAINER>". <VALUE>
/ #进入后再执行与故障相关的检查。--target 会请求让调试容器面向目标容器的进程环境,但能否看到目标进程仍取决于容器运行时和 Pod 的进程命名空间设置;受限集群也可能被准入策略拒绝创建临时容器。
排障时应保留这个顺序:先看状态、Conditions 与 Events,再看当前和上一轮日志;只有需要验证运行时环境时才 exec,需要绕过 Service 链路时才 port-forward,业务镜像缺少工具时再使用临时调试容器。这样可以减少“先重启导致证据丢失”的情况。