kubectl-debugging

kubectl debug - Kubernetes 交互式调试

使用 kubectl debug 调试 Kubernetes 资源的专业知识——临时容器、Pod 副本和节点访问。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 ……
使用 kubectl debug 将临时调试容器附加到正在运行的 Pod	对于常规 kubectl 工作流（apply、get、describe、logs），请使用 kubernetes-operations
创建使用不同镜像或命令的 Pod 副本，以便交互式排查问题	如果故障出在模板渲染或 Chart 配置，而非正在运行的容器，请使用 helm-debugging
打开节点级调试会话，以检查主机命名空间或文件系统	如果恢复操作是 Helm 回滚，而非针对单个 Pod 的调试，请使用 helm-release-recovery

核心功能

kubectl debug 可自动执行常见调试任务：

• 临时容器：向正在运行的 Pod 添加调试容器，无需重启
• Pod 副本：创建修改后的副本以进行调试（使用不同的镜像、命令）
• 节点调试：访问节点主机命名空间和文件系统

上下文安全（重要）

始终在每条 kubectl 命令中显式指定 --context：

# CORRECT: Explicit context
kubectl --context=prod-cluster debug mypod -it --image=busybox

# WRONG: Relying on current context
kubectl debug mypod -it --image=busybox  # Which cluster?

快速参考

添加临时调试容器

# Interactive debugging with busybox
kubectl --context=my-context debug mypod -it --image=busybox

# Target specific container's process namespace
kubectl --context=my-context debug mypod -it --image=busybox --target=mycontainer

# Use a specific debug profile
kubectl --context=my-context debug mypod -it --image=busybox --profile=netadmin

复制 Pod 以进行调试

# Create debug copy
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --image=busybox

# Copy and change container image
kubectl --context=my-context debug mypod --copy-to=mypod-debug --set-image=app=busybox

# Copy and modify command
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --container=myapp -- sh

# Copy on same node
kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --same-node --image=busybox

调试节点

# Interactive node debugging (host namespaces, filesystem at /host)
kubectl --context=my-context debug node/mynode -it --image=busybox

# With sysadmin profile for full capabilities
kubectl --context=my-context debug node/mynode -it --image=ubuntu --profile=sysadmin

调试配置文件

配置文件	用例	功能
legacy	默认，不受限制	完全访问权限（向后兼容）
general	通用	中等限制
baseline	最小限制	Pod 安全基线
netadmin	网络故障排查	NET_ADMIN 功能
restricted	高安全性环境	最严格的限制
sysadmin	系统管理	SYS_PTRACE、SYS_ADMIN

# Network debugging (tcpdump, netstat, ss)
kubectl --context=my-context debug mypod -it --image=nicolaka/netshoot --profile=netadmin

# System debugging (strace, perf)
kubectl --context=my-context debug mypod -it --image=ubuntu --profile=sysadmin

常用调试镜像

镜像	大小	用例
busybox	~1MB	基本 Shell、常用实用工具
alpine	~5MB	带 apk 包管理器的 Shell
ubuntu	~77MB	带 apt 的完整 Linux
nicolaka/netshoot	~350MB	网络调试（tcpdump、dig、curl、netstat）
gcr.io/k8s-debug/debug	不定	Kubernetes 官方调试镜像

调试模式

网络连接问题

# Add netshoot container for network debugging
kubectl --context=my-context debug mypod -it \
  --image=nicolaka/netshoot \
  --profile=netadmin

# Inside container:
# - tcpdump -i any port 80
# - dig kubernetes.default
# - curl -v http://service:port
# - ss -tlnp
# - netstat -an

应用崩溃

# Copy pod with different entrypoint to inspect
kubectl --context=my-context debug mypod -it \
  --copy-to=mypod-debug \
  --container=app \
  -- sh

# Inside: check filesystem, env vars, config files

进程检查

# Target container's process namespace
kubectl --context=my-context debug mypod -it \
  --image=busybox \
  --target=mycontainer

# Inside: ps aux, /proc inspection

节点级问题

# Debug node with host access
kubectl --context=my-context debug node/worker-1 -it \
  --image=ubuntu \
  --profile=sysadmin

# Inside:
# - Host filesystem at /host
# - chroot /host for full access
# - journalctl, systemctl, dmesg

非破坏性调试

# Create copy, keeping original running
kubectl --context=my-context debug mypod -it \
  --copy-to=mypod-debug \
  --same-node \
  --share-processes \
  --image=busybox

# Original pod continues serving traffic
# Debug copy shares storage if on same node

重要选项

选项	说明
-it	交互式 TTY（访问 Shell 时必需）
--image	调试容器镜像
--container	调试容器的名称
--target	与此容器共享进程命名空间
--copy-to	创建副本，而非临时容器
--same-node	在同一节点上调度副本（与 --copy-to 一起使用）
--set-image	更改副本中的容器镜像
--profile	安全配置文件（legacy、netadmin、sysadmin 等）
--share-processes	启用进程命名空间共享（使用 --copy-to 时默认为 true）
--replace	创建副本时删除原始 Pod

最佳实践

1. 使用恰当的配置文件——根据调试需求选择功能
2. 优先使用临时容器——比 Pod 副本的影响更小
3. 对侵入性调试使用 --copy-to——保留原始 Pod
4. 清理调试 Pod——调试完成后删除副本
5. 使用 --same-node——访问共享存储或网络环境时使用

清理

# List debug pod copies
kubectl --context=my-context get pods | grep -E "debug|copy"

# Delete debug pods
kubectl --context=my-context delete pod mypod-debug

要求

• 临时容器需要 Kubernetes 1.23+（稳定版）
• 调试配置文件需要 Kubernetes 1.25+
• 需要 pods/ephemeralcontainers 的 RBAC 权限

有关选项的详细参考、示例和故障排查模式，请参阅 REFERENCE.md。