kubectl debug 是什么
生产镜像普遍是精简甚至 distroless 的，容器里没有 shell、没有 curl，exec 进去等于进入一个什么都做不了的环境。kubectl debug 通过注入临时容器（ephemeral container）解决这一问题：临时容器与目标容器共享进程、网络命名空间，自带工具集，用完即弃，不需要修改业务镜像或重建 Pod。
基本信息
| Pod 内调试 | kubectl debug -it <pod> --image=... --target=<容器> |
|---|---|
| 复制重建 | --copy-to 复制一份 Pod 并改 spec，用于复现启动问题 |
| 节点级调试 | kubectl debug node/<节点> -it，宿主根文件系统挂在 /host |
| 关键参数 | --target 让临时容器共享目标容器的进程命名空间 |
| 限制 | 临时容器不能配端口与资源，仅用于调试 |
| 版本要求 | 依赖临时容器能力，Kubernetes 1.25 起转正 |
三种调试方式对比
| 方式 | 适用场景 | 注意 |
|---|---|---|
| Pod 内临时容器 | 容器无 shell，要抓包或看进程 | 不加 --target 看不到业务进程 |
| --copy-to 复制 Pod | 要改镜像或命令复现启动失败 | 副本会占资源，调试后清理 |
| kubectl exec | 镜像里有 shell 且工具够用 | distroless 上直接失败 |
| 节点级调试 | 查 kubelet、内核、宿主网络 | 需较高权限，宿主根在 /host |
调试命令
调试命令
kubectl debug -it web-1 --image=nicolaka/netshoot --target=web # 进同进程命名空间
# 以下是临时容器内执行的命令
ps aux # --target 生效时能看到业务进程
nc -vz db.dev 3306
kubectl debug web-1 --copy-to=web-debug --image=myapp:1.2.3 -- sleep 3600 # 复制并改配置
kubectl debug node/node-1 -it --image=busybox # 节点级：宿主挂载到 /host
cat /host/etc/os-release典型使用场景
- 容器里没有 curl 或 ss，需要临时工具验证网络链路
- 抓包定位偶发连接超时，用临时容器里的 tcpdump 观察流量
- 复现带配置变更的启动失败，需要复制 Pod 改 spec 而不动线上对象
- 排查节点级问题：kubelet 报错、内核参数、宿主防火墙规则
- 确认业务进程到底有没有起来，用共享进程命名空间后 ps 一眼看出
容器没 shell 时应优先注入临时调试容器，而不是重建业务 Pod；只有必须改变镜像或启动命令才能复现的问题，才用 --copy-to 复制一份。
临时容器里做的改动只存在于该 Pod 的生命周期内，删除 Pod 即消失，也不会进入任何镜像；正式修复仍然要回到 Dockerfile 或清单里。
节点级调试会把宿主根文件系统挂进容器，误删或误改宿主文件可能直接搞垮节点，只读为主，写操作要极其克制。