Kubernetes Debug Container

satwik raj — Wed, 24 Sep 2025 18:53:30 +0000

What is the use of the “kubectl debug” command?

What is a Debug Container?

→ Let’s say there is a situation where a pod is running and it does not have any pre-installed tools like netstat, curl, and ping because of safety issues and to make the container lightweight. Then, in that case, we use a debug container. A debug container is a container that has debugging tools installed inside it, and it is attached to a running container to resolve issues. It is a Container, not a Pod.

Example:-
The image below shows a Pod, nginx-pod, running in the default namespace. Inside the nginx-pod, a container is running with the name nginx-container, as you can see below.

Now let's assume nginx-container does not have any debug tools like ping, curl, netstat, and that container encountered some network issue, like the nginx web page is not accessible on the running port.

So to solve this issue, we have 2 options: -

Either stop the running pod of nginx-pod and container nginx-container and install tools inside it, and then redeploy those pods with the container.
Run a parallel container where we can test what issue is there through the CLI.

So here we are going to discuss the 2nd scenario.

In this, we are creating a new container called debug-container.

Here in the above image you can see nginx-pod and nginx-container is running.

Now we are going to create a new container debug-container in the nginx-pod which will have busybox image inside it. Busybox image container will share the same network namespace with the nginx-container, so we can run any command on the busybox container will be executed as command on the nignx-container.

Temporary busybox container in the same network and PID namespace as the NGINX container.

Now, in the below image, as you can see, I ran a command wget -q0- http://127.0.0.1:80 → this command gave the output because the nginx and busybox containers share the same network namespace.

Commands used: -

kubectl run nginx-pod --image=nginx #(in order to name the container use manifest file)

kubectl get pods # This command is use to list all the pods

kubectl debug -it nginx-pod --image=busybox # This command is used to create a debug container inside the nginx-pod

After running the above command a terminal will open of busybox, type the below command
wget -qO- http://127.0.0.1:80

Network namespace (net ns)

All containers in a pod share the same network namespace.

This means:

They share the same IP address.

Ports exposed by one container (like NGINX:80) are accessible from other containers using localhost or pod IP.

wget -qO- http://127.0.0.1:80 from the debug container works, even though NGINX is in a different container.

PID namespace (process ID)

By default, each container has its own PID namespace.

Processes inside NGINX container cannot see processes inside busybox container, and vice versa.