kubectl debug - Interactive Kubernetes Debugging

kubectl debug - Kubernetes交互式调试

Expert knowledge for debugging Kubernetes resources using

kubectl debug

- ephemeral containers, pod copies, and node access.

本文提供使用

kubectl debug

调试Kubernetes资源的专业知识，包括临时容器、Pod复制和节点访问。

Core Capabilities

核心功能

kubectl debug automates common debugging tasks:

Ephemeral Containers: Add debug containers to running pods without restart
Pod Copying: Create modified copies for debugging (different images, commands)
Node Debugging: Access node host namespaces and filesystem

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

Ephemeral Containers：无需重启即可向运行中的Pod添加调试容器
Pod复制：创建经过修改的Pod副本用于调试（如更换镜像、命令）
节点调试：访问节点主机命名空间和文件系统

Context Safety (CRITICAL)

上下文安全性（至关重要）

Always specify
--context
explicitly in every kubectl command:

bash

undefined

务必在每个kubectl命令中显式指定
--context
：

bash

undefined

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?

undefined

kubectl debug mypod -it --image=busybox # 指向哪个集群？

undefined

Quick Reference

快速参考

Add Ephemeral Debug Container

添加临时调试容器

bash

undefined

bash

undefined

Interactive debugging with busybox

使用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

undefined

kubectl --context=my-context debug mypod -it --image=busybox --profile=netadmin

undefined

Copy Pod for Debugging

复制Pod用于调试

bash

undefined

bash

undefined

Create debug copy

创建调试副本

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

Copy and change container image

复制Pod并更换容器镜像

kubectl --context=my-context debug mypod --copy-to=mypod-debug --set-image=app=busybox

Copy and modify command

复制Pod并修改启动命令

kubectl --context=my-context debug mypod -it --copy-to=mypod-debug --container=myapp -- sh

Copy on same node

在同一节点上复制Pod

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

undefined

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

undefined

Debug Node

调试节点

bash

undefined

bash

undefined

Interactive node debugging (host namespaces, filesystem at /host)

交互式节点调试（主机命名空间，文件系统挂载在/host）

kubectl --context=my-context debug node/mynode -it --image=busybox

With sysadmin profile for full capabilities

使用sysadmin配置文件获取完整权限

kubectl --context=my-context debug node/mynode -it --image=ubuntu --profile=sysadmin

undefined

kubectl --context=my-context debug node/mynode -it --image=ubuntu --profile=sysadmin

undefined

Debug Profiles

调试配置文件

Profile	Use Case	Capabilities
`legacy`	Default, unrestricted	Full access (backwards compatible)
`general`	General purpose	Moderate restrictions
`baseline`	Minimal restrictions	Pod security baseline
`netadmin`	Network troubleshooting	NET_ADMIN capability
`restricted`	High security environments	Strictest restrictions
`sysadmin`	System administration	SYS_PTRACE, SYS_ADMIN

bash

undefined

配置文件	适用场景	功能
`legacy`	默认选项，无限制	完全访问权限（向后兼容）
`general`	通用场景	中等权限限制
`baseline`	最小权限限制	符合Pod安全基线
`netadmin`	网络故障排查	拥有NET_ADMIN权限
`restricted`	高安全环境	最严格的权限限制
`sysadmin`	系统管理	拥有SYS_PTRACE、SYS_ADMIN权限

bash

undefined

Network debugging (tcpdump, netstat, ss)

网络调试（tcpdump、netstat、ss）

kubectl --context=my-context debug mypod -it --image=nicolaka/netshoot --profile=netadmin

System debugging (strace, perf)

系统调试（strace、perf）

kubectl --context=my-context debug mypod -it --image=ubuntu --profile=sysadmin

undefined

kubectl --context=my-context debug mypod -it --image=ubuntu --profile=sysadmin

undefined

Common Debug Images

常用调试镜像

Image	Size	Use Case
`busybox`	~1MB	Basic shell, common utilities
`alpine`	~5MB	Shell with apk package manager
`ubuntu`	~77MB	Full Linux with apt
`nicolaka/netshoot`	~350MB	Network debugging (tcpdump, dig, curl, netstat)
`gcr.io/k8s-debug/debug`	Varies	Official Kubernetes debug image

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

Debugging Patterns

调试模式

Network Connectivity Issues

网络连接问题

bash

undefined

bash

undefined

Add netshoot container for network debugging

添加netshoot容器进行网络调试

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

undefined

undefined

Application Crashes

应用崩溃问题

bash

undefined

bash

undefined

Copy pod with different entrypoint to inspect

复制Pod并修改入口命令以进行检查

kubectl --context=my-context debug mypod -it
--copy-to=mypod-debug
--container=app
-- sh

Inside: check filesystem, env vars, config files

在容器内：检查文件系统、环境变量、配置文件

undefined

undefined

Process Inspection

进程检查

bash

undefined

bash

undefined

Target container's process namespace

关联目标容器的进程命名空间

kubectl --context=my-context debug mypod -it
--image=busybox
--target=mycontainer

Inside: ps aux, /proc inspection

在容器内：执行ps aux、检查/proc目录

undefined

undefined

Node-Level Issues

节点级问题

bash

undefined

bash

undefined

Debug node with host access

调试节点并获取主机访问权限

kubectl --context=my-context debug node/worker-1 -it
--image=ubuntu
--profile=sysadmin

Inside:

在容器内：

- Host filesystem at /host

- 主机文件系统挂载在/host

- chroot /host for full access

- 执行chroot /host获取完整主机访问权限

- journalctl, systemctl, dmesg

- 执行journalctl、systemctl、dmesg

undefined

undefined

Non-Destructive Debugging

非破坏性调试

bash

undefined

bash

undefined

Create copy, keeping original running

创建Pod副本，保持原Pod运行

kubectl --context=my-context debug mypod -it
--copy-to=mypod-debug
--same-node
--share-processes
--image=busybox

Original pod continues serving traffic

原Pod继续处理流量

Debug copy shares storage if on same node

调试副本在同一节点时可访问共享存储

undefined

undefined

Key Options

关键选项

Option	Description
`-it`	Interactive TTY (required for shell access)
`--image`	Debug container image
`--container`	Name for the debug container
`--target`	Share process namespace with this container
`--copy-to`	Create a copy instead of ephemeral container
`--same-node`	Schedule copy on same node (with `--copy-to` )
`--set-image`	Change container images in copy
`--profile`	Security profile (legacy, netadmin, sysadmin, etc.)
`--share-processes`	Enable process namespace sharing (default: true with --copy-to)
`--replace`	Delete original pod when creating copy

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

Best Practices

最佳实践

Use appropriate profiles - Match capabilities to debugging needs
Prefer ephemeral containers - Less disruptive than pod copies
Use
--copy-to
for invasive debugging - Preserve original pod
Clean up debug pods - Delete copies after debugging
Use
--same-node
- For accessing shared storage/network conditions

使用合适的配置文件 - 根据调试需求匹配对应权限
优先使用临时容器 - 比Pod副本的破坏性更小
侵入式调试使用
--copy-to
- 保留原Pod不受影响
清理调试Pod - 调试完成后删除副本
使用
--same-node
- 用于访问共享存储/网络环境

Cleanup

清理

bash

undefined

bash

undefined

List debug pod copies

列出调试Pod副本

kubectl --context=my-context get pods | grep -E "debug|copy"

Delete debug pods

删除调试Pod

kubectl --context=my-context delete pod mypod-debug

undefined

kubectl --context=my-context delete pod mypod-debug

undefined

Requirements

要求

Kubernetes 1.23+ for ephemeral containers (stable)
Kubernetes 1.25+ for debug profiles
RBAC permissions for pods/ephemeralcontainers

For detailed option reference, examples, and troubleshooting patterns, see REFERENCE.md.

Kubernetes 1.23+ 支持稳定版临时容器
Kubernetes 1.25+ 支持调试配置文件
拥有Pods/ephemeralcontainers的RBAC权限

如需详细的选项参考、示例和故障排查模式，请查看REFERENCE.md。

kubectl-debugging

Original

Translation

kubectl debug - Interactive Kubernetes Debugging

kubectl debug - Kubernetes交互式调试

Core Capabilities

核心功能

Context Safety (CRITICAL)

上下文安全性（至关重要）

CORRECT: Explicit context

正确用法：显式指定上下文

WRONG: Relying on current context

错误用法：依赖当前上下文

Quick Reference

快速参考

Add Ephemeral Debug Container

添加临时调试容器

Interactive debugging with busybox

使用busybox进行交互式调试

Target specific container's process namespace

关联特定容器的进程命名空间

Use a specific debug profile

使用特定调试配置文件

Copy Pod for Debugging

复制Pod用于调试

Create debug copy

创建调试副本

Copy and change container image

复制Pod并更换容器镜像

Copy and modify command

复制Pod并修改启动命令

Copy on same node

在同一节点上复制Pod

Debug Node

调试节点

Interactive node debugging (host namespaces, filesystem at /host)

交互式节点调试（主机命名空间，文件系统挂载在/host）

With sysadmin profile for full capabilities

使用sysadmin配置文件获取完整权限

Debug Profiles

调试配置文件

Network debugging (tcpdump, netstat, ss)

网络调试（tcpdump、netstat、ss）

System debugging (strace, perf)

系统调试（strace、perf）

Common Debug Images

常用调试镜像

Debugging Patterns

调试模式

Network Connectivity Issues

网络连接问题

Add netshoot container for network debugging

添加netshoot容器进行网络调试

Inside container:

在容器内执行：

- tcpdump -i any port 80

- tcpdump -i any port 80

- dig kubernetes.default

- dig kubernetes.default

- curl -v http://service:port

- curl -v http://service:port

- ss -tlnp

- ss -tlnp

- netstat -an

- netstat -an

Application Crashes

应用崩溃问题

Copy pod with different entrypoint to inspect

复制Pod并修改入口命令以进行检查

Inside: check filesystem, env vars, config files

在容器内：检查文件系统、环境变量、配置文件

Process Inspection

进程检查

Target container's process namespace

关联目标容器的进程命名空间

Inside: ps aux, /proc inspection

在容器内：执行ps aux、检查/proc目录

Node-Level Issues

节点级问题

Debug node with host access