Buy now

How to Investigate Problems with Kubernetes Containers Using Kubectl Debug

It can be difficult to diagnose problems running Kubernetes workloads. You might get lucky and find the cause in your application’s logs about the kubectl logs Command. However, in some cases there is no avoiding a live debugging session, where you interact interactively with your pods to uncover problems.

That kubectl debug The command simplifies these debugging tasks by providing a new ephemeral container in your pod. This can be used to examine the pod’s environment so you can start troubleshooting issues that crop up in your existing containers.

Prepare to use Kubectl Debug

kubectl debug was launched with v1.18 of Kubernetes and Kubectl. It relies on ephemeral containers being available in your cluster. Ephemeral containers became a beta feature in Kubernetes v1.23 and are now enabled by default. You must manually enable the Feature Gate if your cluster is running an older version of Kubernetes.

Ephemeral containers are designed for temporary tasks where you need to temporarily connect an additional container to an existing pod. This is ideal for debugging operations where you want to examine a pod closely without affecting live container instances.

Most container images lack debugging tools; Installing in a running container would change its environment and potentially cause side effects. Attaching an ephemeral container to your pod is a safer method of debugging that gives you a clean working environment. You can use a heavier image that has all the tools you need.

Although ephemeral containers become part of their host pod, there are still some differences to be aware of. Ephemeral containers don’t support port bindings, probes, or resource reservations as they are temporary in nature. They are never automatically restarted and cannot be modified once created. See the documentation for a full list of supported features.

Using Kubectl Debug

Before proceeding, create a simple deployment for testing purposes:

$ kubectl create deployment nginx --image=nginx:latest
deployment.apps/nginx created

Next, use the get pods Command to find the name of your deployment’s pod:

$ kubectl get pods
NAME                     READY   STATUS    RESTARTS   AGE
nginx-55649fd747-qsnr2   1/1     Running   0          5s

Our deployment’s pod is called nginx-55649fd747-qsnr2.

Now you can use them kubectl debug Command to start a debugging session in your pod:

$ kubectl debug -it --image=ubuntu:20.04 nginx-55649fd747-qsnr2

The syntax of the command resembles a mixture of kubectl create and kubectl debug. The unnamed argument provided to the command identifies an existing pod to connect to. That --image The argument specifies the image to use for the new container. We use ubuntu:20.04 here to get access to the familiar commands that come with the Ubuntu Linux distribution.

That -it Flag is synonymous with --stdin --tty. Including these arguments assigns a tty to the container, appends it, and connects your terminal’s stdin stream. This will give you an interactive shell in your new container.

Now you can run your debugging tasks in your ephemeral container.

Copy pod

A different way of using it kubectl debug is with a --copy-to Fight. This creates a copy of the target pod and adds the ephemeral container to the copy. The original pod remains intact.

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug nginx-555649fd747-qsnr2

This feature gives you even greater assurance that changes made while debugging will not directly affect your production application.

You can also enable process namespace sharing by copying the pod. This makes the existing processes in your pod visible to your ephemeral container. It cannot be used with existing containers as theirs spec.shareProcessNamespace The field is normally set to false. operation kubectl debug with the --copy-to and --share-processes Flag enables process sharing on the copied pod, making this procedure much more intuitive:

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --share-processes nginx-555649fd747-qsnr2

The process list visible to your ephemeral Ubuntu container now contains an NGINX process:

$ ps ax
    1 root      0:00 /pause
    9 root      0:00 nginx: master process nginx -g daemon off;

This process still runs in the separate NGINX container in your pod. The namespace share also provides access to the target container’s file system via /proc:

$ ls /proc/9/root/etc/nginx
conf.d fastcgi_params mime.types modules nginx.conf ...

So, copying the pod this way is a powerful debugging tool. You can easily inspect the pod’s files and processes using a separate container prepared with familiar tools.

Optional arguments

That --copy-to flag always leaves the original pod intact by default. You can use the operation as a replacement instead --replace. This will stop the first pod.

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --replace nginx-555649fd747-qsnr2

Kubernetes schedules the copied pod for each available node. This can be problematic if you want to ensure a consistent test environment. Add to --same-node schedules the copy on the existing pod nodes and eliminates any differences that may exist between machines in your cluster.

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --same-node nginx-555649fd747-qsnr2

Another useful option is --env to set additional environment variables in your ephemeral container. You may need to use this to configure debugging tools or to override values ​​inherited from your target pod.

$ kubectl debug -it --image=ubuntu:20.04 --copy-to nginx-debug --env EDITOR=/usr/bin/nano nginx-555649fd747-qsnr2

Finally, remember that containers were created by kubectl debug don’t have to be interactive. With you can easily run one-time commands on your pods kubectl exec-like syntax. That --attach -argument is supported to control whether your shell is connected to the container when you are not running it -i (--stdin).

$ kubectl debug --image=ubuntu:20.04 --copy-to nginx-debug --share-processes --attach true nginx-555649fd747-qsnr2 -- ls /proc/9/root/etc/nginx
conf.d fastcgi_params mime.types modules nginx.conf ...


Ephemeral containers and the kubectl debug commands provide a simplified debugging experience for Kubernetes workloads. You can run commands inside a pod with a different image than your regular containers. This gives you access to debugging tools that are not included in your application’s image.

kubectl debug can also create copies of pods and share their processes with the original. This mechanism allows you to inspect the processes in the target pod’s containers from a separate ephemeral container over which you have full control. It offers advanced debugging options when you need to query running processes. Tech News Click here

Subscribe to Our YouTube, Instagram and Twitter – TwitterYoutube and Instagram.

( Story and Image Credit – Source )

Related Articles

Leave a Reply

Stay Connected


Latest Articles