kubectl debug

概要 (Synopsis)

使用交互式调试容器调试集群资源。

'debug' 命令为根据资源和名称标识的集群对象提供了常见的自动化调试任务。 如果未指定资源，默认使用 Pod。

'debug' 命令执行的操作取决于指定的资源。支持的操作包括：

  • 工作负载：创建一个现有 Pod 的副本，并更改其某些属性，例如将镜像标签更改为新版本。
  • 工作负载：向已经运行的 Pod 中添加一个临时容器，例如在不重启 Pod 的情况下添加调试工具。
  • 节点：创建一个新的 Pod，该 Pod 在节点的宿主命名空间中运行，并且可以访问节点的 文件系统。

注意：当整个目标 Pod 配置了非 root 用户时，调试配置文件授予的某些能力可能无法工作。

kubectl debug (POD | TYPE[[.VERSION].GROUP]/NAME) [ -- COMMAND [args...] ]

示例 (Examples)

  # Create an interactive debugging session in pod mypod and immediately attach to it.
  kubectl debug mypod -it --image=busybox
  
  # Create an interactive debugging session for the pod in the file pod.yaml and immediately attach to it.
  # (requires the EphemeralContainers feature to be enabled in the cluster)
  kubectl debug -f pod.yaml -it --image=busybox
  
  # Create a debug container named debugger using a custom automated debugging image.
  kubectl debug --image=myproj/debug-tools -c debugger mypod
  
  # Create a copy of mypod adding a debug container and attach to it
  kubectl debug mypod -it --image=busybox --copy-to=my-debugger
  
  # Create a copy of mypod changing the command of mycontainer
  kubectl debug mypod -it --copy-to=my-debugger --container=mycontainer -- sh
  
  # Create a copy of mypod changing all container images to busybox
  kubectl debug mypod --copy-to=my-debugger --set-image=*=busybox
  
  # Create a copy of mypod adding a debug container and changing container images
  kubectl debug mypod -it --copy-to=my-debugger --image=debian --set-image=app=app:debug,sidecar=sidecar:debug
  
  # Create an interactive debugging session on a node and immediately attach to it.
  # The container will run in the host namespaces and the host's filesystem will be mounted at /host
  kubectl debug node/mynode -it --image=busybox

选项 (Options)

--arguments-only

如果指定此参数，则在 -- 之后的所有内容都将作为 Args（而不是 Command）传递给新的容器。

--attach

如果为 true，则等待容器开始运行，然后附加到容器，就像调用了 'kubectl attach ...'。默认值为 false，除非设置了 '-i/--stdin'，在这种情况下默认值为 true。

-c, --container string

用于调试容器的容器名称。

--copy-to string

创建目标 Pod 的副本，并指定此名称。

--custom string

包含部分容器规约（spec）的 JSON 或 YAML 文件的路径，用于定制内置的调试配置文件。

--env stringToString     Default: []

在容器中设置的环境变量。

-f, --filename strings

标识要调试的资源。

-h, --help

debug 命令的帮助信息。

--image string

用于调试容器的容器镜像。

--image-pull-policy string

容器的镜像拉取策略。如果留空，则此值不会由客户端指定，而由服务器默认设置。

--keep-annotations

如果为 true，则保留原始 Pod 的注解。（此参数仅在使用 '--copy-to' 时有效）

--keep-init-containers     Default: true

运行 Pod 的 init 容器。默认为 true。（此参数仅在使用 '--copy-to' 时有效）

--keep-labels

如果为 true，则保留原始 Pod 的标签。（此参数仅在使用 '--copy-to' 时有效）

--keep-liveness

如果为 true，则保留原始 Pod 的存活探针（liveness probes）。（此参数仅在使用 '--copy-to' 时有效）

--keep-readiness

如果为 true，则保留原始 Pod 的就绪探针（readiness probes）。（此参数仅在使用 '--copy-to' 时有效）

--keep-startup

如果为 true，则保留原始 Pod 的启动探针（startup probes）。（此参数仅在使用 '--copy-to' 时有效）

--profile string     Default: "legacy"

可选值包括 "legacy"、"general"、"baseline"、"netadmin"、"restricted" 或 "sysadmin"。

-q, --quiet

如果为 true，则抑制信息消息。

--replace

与 '--copy-to' 一起使用时，删除原始 Pod。

--same-node

与 '--copy-to' 一起使用时，将目标 Pod 的副本调度到同一节点上。

--set-image stringToString     Default: []

与 '--copy-to' 一起使用时，提供 name=image 对列表来更改容器镜像，其工作方式类似于 'kubectl set image'。

--share-processes     Default: true

与 '--copy-to' 一起使用时，在副本中启用进程命名空间共享。

-i, --stdin

在 Pod 中的一个或多个容器上保持标准输入流（stdin）打开，即使没有附加任何内容。

--target string

使用临时容器时，以该容器名称为目标进程。

-t, --tty

为调试容器分配一个 TTY。

继承的父级选项 (Parent Options Inherited)

--as string

操作时要模拟的用户名。用户可以是普通用户，也可以是命名空间中的服务账号。

--as-group strings

操作时要模拟的组名，此参数可重复以指定多个组。

--as-uid string

操作时要模拟的 UID。

--cache-dir string     Default: "$HOME/.kube/cache"

默认缓存目录。

--certificate-authority string

证书颁发机构的证书文件路径。

--client-certificate string

用于 TLS 的客户端证书文件路径。

--client-key string

用于 TLS 的客户端密钥文件路径。

--cluster string

要使用的 kubeconfig 集群名称。

--context string

要使用的 kubeconfig 上下文名称。

--default-not-ready-toleration-seconds int     Default: 300

表示为每个尚不存在此类容忍度的 Pod 默认添加的针对 notReady:NoExecute 的容忍度秒数（tolerationSeconds）。

--default-unreachable-toleration-seconds int     Default: 300

表示为每个尚不存在此类容忍度的 Pod 默认添加的针对 unreachable:NoExecute 的容忍度秒数（tolerationSeconds）。

--disable-compression

如果为 true，则对发送到服务器的所有请求不使用响应压缩。

--insecure-skip-tls-verify

如果为 true，则不会检查服务器证书的有效性。这会使你的 HTTPS 连接不安全。

--kubeconfig string

用于 CLI 请求的 kubeconfig 文件路径。

--match-server-version

要求服务器版本与客户端版本匹配。

-n, --namespace string

如果指定，则表示此 CLI 请求的命名空间范围。

--password string

连接 API 服务器进行基本认证的密码。

--profile-output string     Default: "profile.pprof"

写入性能分析数据的文件名。

--request-timeout string     Default: "0"

在放弃单个服务器请求之前等待的时间长度。非零值应包含对应的时间单位（例如 1s、2m、3h）。值为零表示不设置请求超时。

-s, --server string

Kubernetes API 服务器的地址和端口。

--storage-driver-buffer-duration duration     Default: 1m0s

存储驱动程序中的写入将在此持续时间内缓冲，并作为单个事务提交给非内存后端。

--storage-driver-db string     Default: "cadvisor"

数据库名称。

--storage-driver-host string     Default: "localhost:8086"

数据库主机:端口。

--storage-driver-password string     Default: "root"

数据库密码。

--storage-driver-secure

使用安全连接连接到数据库。

--storage-driver-table string     Default: "stats"

表名。

--storage-driver-user string     Default: "root"

数据库用户名。

--tls-server-name string

用于服务器证书验证的服务器名称。如果未提供，则使用用于连接服务器的主机名。

--token string

连接 API 服务器进行身份验证的 Bearer Token。

--user string

要使用的 kubeconfig 用户名。

--username string

连接 API 服务器进行基本认证的用户名。

--version version[=true]

--version、--version=raw 打印版本信息并退出；--version=vX.Y.Z... 设置报告的版本。

--warnings-as-errors

将从服务器收到的警告视为错误并以非零退出码退出。

另请参阅 (See Also)

  • kubectl - kubectl 控制 Kubernetes 集群管理器

本页面是自动生成的。

如果你打算报告此页面的问题，请在问题描述中提及该页面是自动生成的。修复可能需要在 Kubernetes 项目的其他地方进行。

最后修改于 2025 年 4 月 24 日 8:03 AM PST：kubectl 参考文档 v1.33 (80481646c3)