排障工具箱 kubectl debug / Ephemeral Containers

面向需要进入 Pod/节点排查但生产镜像极简（distroless，无 shell）的工程师。覆盖临时容器、Pod 复制、节点调试三种手段。

适用版本与前提

• Kubernetes：v1.25+（kubectl debug 的 ephemeral 与节点调试在该版本进入稳定/可用状态）[版本相关]
• 前提：有目标命名空间 Pod 的 get/patch 权限；节点调试需更高权限
• 背景：很多生产镜像是 distroless 或 scratch，没有 sh/curl/netstat，传统 kubectl exec 无从下手

背景与问题

常见困境：

• 镜像里没有 sh，kubectl exec -it pod -- sh 直接失败。
• 想抓包/看进程，但无法安装工具（镜像只读或不允许改）。
• 节点层面想看，但没有 SSH 权限。

kubectl debug 的三板斧正是为此设计：

核心概念

手段	作用	是否改动原 Pod
临时容器（ephemeral container）	往运行中的 Pod 注入一个调试容器，共享目标容器的进程/网络命名空间	会修改 Pod spec（添加 ephemeralContainers）
--copy-to	复制出一个新 Pod（可换镜像、加特权、改命令），原 Pod 不动	不改原 Pod
节点调试	在目标节点上起一个特权 Pod，把宿主 / 挂进来	不改业务 Pod（但会占用节点资源）

注意

临时容器不支持在 Pod 创建后加入 resources、探针等字段，且 Pod 重建后消失。它是一次性的诊断手段，不是配置手段。

生产实践

1. 临时容器：进入目标容器的命名空间

# 注入带工具的调试容器，共享目标容器的进程命名空间
kubectl debug -n prod <pod> -it \
  --image=busybox:1.36 \
  --target=<container-name> \
  -- sh

进入后可：

# 看目标容器的进程（因共享 PID 命名空间）
ps aux

# 看网络（共享网络命名空间）
netstat -tlnp 2>/dev/null || ss -tlnp
cat /etc/resolv.conf
nslookup <service>
wget -qO- http://127.0.0.1:8080/healthz

建议

用 nicolaka/netshoot 这类专用排障镜像（含 tcpdump/dig/curl/iperf），比 busybox 更实用。但不要在生产长期依赖外部镜像，建议内部镜像仓库同步一份。

kubectl debug -n prod <pod> -it \
  --image=netshoot \
  --target=<container-name> \
  -- bash

2. 复制 Pod：完整复现且不干扰原 Pod

# 复制一份，换镜像、加特权，用于深入排查
kubectl debug -n prod <pod> -it \
  --copy-to=debug-copy \
  --image=netshoot \
  --share-processes \
  -- bash

# 复制并替换启动命令（排查启动即崩溃）
kubectl debug -n prod <pod> -it \
  --copy-to=debug-crash \
  --container=<container-name> \
  --set-image=*=registry.internal/app:debug \
  -- sh

注意

复制出的 Pod 会真实运行你的业务镜像，可能产生副作用（写库、发消息、注册服务）。生产环境务必先确认该服务是否有写副作用，必要时在低峰期或影子环境做。

3. 节点调试：没有 SSH 也能看节点

# 在目标节点上启动特权调试 Pod，挂载宿主根文件系统
kubectl debug node/<node-name> -it --image=busybox:1.36 -- chroot /host

# 进入后即可使用宿主工具
ps aux
df -h
journalctl -u kubelet | tail -50     # 宿主 systemd 日志
ls /var/log/containers/ | tail
crictl ps                            # 若宿主有 crictl

生产危险

节点调试会创建一个特权容器并挂载宿主 /，等同获得该节点的 root 权限。用完必须清理，且只能由有资质的运维在审批后执行。严禁在合规敏感环境随意使用。

4. 抓包（网络排障杀手锏）

kubectl debug -n prod <pod> -it --image=netshoot --target=<container> -- bash
# 在调试容器内
tcpdump -i eth0 -nn -s0 -w /tmp/capture.pcap host <peer-ip>
# 拷出分析
kubectl cp <debug-pod>:/tmp/capture.pcap ./capture.pcap -n prod

验证

# 确认临时容器已注入
kubectl get pod <pod> -n prod -o jsonpath='{.spec.ephemeralContainers[*].name}'

# 节点调试 Pod 通常在 default 命名空间
kubectl get pods -n default | grep node-debugger

回滚与清理

调试是入侵性操作，必须清理：

# 临时容器会随 Pod 重建消失，但为整洁可删除重建的 Pod 前先确认业务无影响
kubectl -n prod delete pod <pod>          # 仅在可重建时执行 [危险]

# 复制出来的 Pod 必须删除
kubectl -n prod delete pod debug-copy

# 节点调试 Pod 必须删除（特权容器！）
kubectl delete pod -n default -l app=node-debugger   # 标签以实际为准
kubectl get pods -n default | grep node-debugger

生产危险

遗留的特权调试 Pod 等同于在节点上留了一个后门。每次调试结束都要确认 Pod 已删除，建议纳入变更清单逐条勾销。

故障排查速查表

现象	手段
镜像无 shell，exec 失败	kubectl debug --target 注入 busybox/netshoot
启动即崩溃，来不及 exec	--copy-to + --set-image 换调试镜像或改命令
需要抓包	netshoot tcpdump + kubectl cp
怀疑节点问题但无 SSH	kubectl debug node/<node> + chroot /host
要看容器运行时状态	节点调试内 crictl ps/inspect/logs

常见报错：

报错	原因
ephemeral containers are disabled	集群未启用 EphemeralContainers 特性门控（老集群）[版本相关]
container <name> not found	--target 名字写错，用 kubectl get pod -o jsonpath='{.spec.containers[*].name}' 确认
pods "x" is forbidden	RBAC 无 ephemeralContainers 写权限

kubectl get pod <pod> -n prod -o jsonpath='{.spec.containers[*].name}'
kubectl auth can-i patch pods/ephemeralcontainers -n prod

安全与合规

• 临时容器注入等同修改生产 Pod，会留下审计记录，应走变更流程。
• 节点调试的特权 Pod 风险最高：用完即删，禁止长期驻留。
• 调试镜像要从内部仓库拉取并做漏洞扫描，避免引入供应链风险。
• 调试过程可能接触到生产数据，注意脱敏与合规。

替代方案与权衡

方案	优点	缺点
kubectl debug 临时容器	不改镜像、共享命名空间	改 Pod spec，Pod 重建即失效
--copy-to	不动原 Pod，可改镜像/命令	会真实跑一份业务副本，可能有副作用
节点调试	能看系统层	特权容器，风险最高
在镜像里内置排障工具	随时可用	增大镜像、扩大攻击面（不推荐）

参考资料

• Kubernetes 官方文档：调试运行中的 Pod，访问日期：2026-10-09。
• Kubernetes 官方文档：临时容器，访问日期：2026-10-09。
• Kubernetes 官方文档：kubectl debug 参考，访问日期：2026-10-09。
• Kubernetes 官方文档：用 crictl 调试节点，访问日期：2026-10-09。