LinuxCommandLibrary

kubectl-debug

Debug running Kubernetes pods

TLDR

Create an interactive debugging session in a pod and immediately attach to it

$ kubectl debug [pod_name] [[-it|--stdin --tty]] --image busybox
copy

Create a debug container with a custom image and name
$ kubectl debug --image [image] [[-c|--container]] [container_name] [pod_name]
copy

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/[node_name] [[-it|--stdin --tty]] --image busybox
copy

Create a copy of a pod and add a debug container to it
$ kubectl debug [pod_name] [[-it|--stdin --tty]] --image [image] --copy-to [pod_copy_name]
copy

Create a copy of a pod and change the command of a specific container
$ kubectl debug [pod_name] [[-it|--stdin --tty]] --copy-to [pod_copy_name] --container [container_name] -- [command]
copy

Create a copy of a pod and change the image of a specific container
$ kubectl debug [pod_name] --copy-to [pod_copy_name] --set-image [container_name]=[image]
copy

Create a copy of a pod and change all container images
$ kubectl debug [pod_name] --copy-to [pod_copy_name] --set-image '*=[image]'
copy

Create an ephemeral debug container and target a specific container (useful for debugging distroless containers)
$ kubectl debug [pod_name] [[-it|--stdin --tty]] --image [image] --target [target_container_name]
copy

SYNOPSIS

kubectl debug [OPTIONS] [POD] [--target TARGET]

PARAMETERS

--attach
    Attach to the debug container (default false)

--container string
    Container name (default "debugger-XXXXX")

--copy-to string
    Copy target resource to this name before debugging (default: original + "-debug")

--image string
    Debug container image (default: "busybox:1.28")

--image-pull-policy string
    Image pull policy (default: "IfNotPresent")

--quiet
    Hide debug pod creation logs

--share-volume stringArray
    Volumes to share with debug container (default: [])

--sh-args stringArray
    Shell command and args (default: ["sh"])

--target string
    Deprecated: target resource name (default: POD name)

--tty
    Allocate TTY (implies --stdin)

DESCRIPTION

The kubectl debug command creates an ephemeral debug container attached to a running Pod or Node, allowing interactive troubleshooting without modifying the original resource.

It mounts the same volumes and network namespace as the target, providing shell access or custom tools via a specified image (default: busybox). Ideal for inspecting files, processes, or network issues in production environments.

Supports targeting specific Pods, copying resources before debugging, sharing volumes, and attaching stdin/TTY for interactive sessions. Deprecated --target flag exists for backward compatibility; use positional arguments instead.

Requires Kubernetes 1.23+ with EphemeralContainers feature gate enabled (GA in 1.29). Enhances debugging over kubectl exec by avoiding container restarts.

CAVEATS

Requires EphemeralContainers feature gate (alpha in 1.23, beta 1.27, GA 1.29). Not for modifying target resources. Debug containers are privileged and temporary.

COMMON USAGE

kubectl debug mypod -it --image=ubuntu --share-volume=shared-data -- /bin/bash
Starts interactive bash in Ubuntu debug container sharing volumes.

NODE DEBUG

kubectl debug node/mynode -it --image=busybox
Debugs node via privileged container (requires node access permissions).

HISTORY

Introduced in Kubernetes v1.23 (alpha), beta in v1.27, stable in v1.29 as part of core kubectl for ephemeral container support.

SEE ALSO

kubectl exec(1), kubectl run(1), kubectl describe(1)

Copied to clipboard