Debug Running Pods

This page explains how to debug Pods running (or crashing) on a Node.

Before you begin

  • Your Pod should already be scheduled and running. If your Pod is not yet running, start with Troubleshoot Applications.
  • For some of the advanced debugging steps you need to know on which Node the Pod is running and have shell access to run commands on that Node. You don’t need that access to run the standard debug steps that use kubectl.

Examining pod logs

First, look at the logs of the affected container:

  1. kubectl logs ${POD_NAME} ${CONTAINER_NAME}

If your container has previously crashed, you can access the previous container’s crash log with:

  1. kubectl logs --previous ${POD_NAME} ${CONTAINER_NAME}

Debugging with container exec

If the container image includes debugging utilities, as is the case with images built from Linux and Windows OS base images, you can run commands inside a specific container with kubectl exec:

  1. kubectl exec ${POD_NAME} -c ${CONTAINER_NAME} -- ${CMD} ${ARG1} ${ARG2} ... ${ARGN}

Note: -c ${CONTAINER_NAME} is optional. You can omit it for Pods that only contain a single container.

As an example, to look at the logs from a running Cassandra pod, you might run

  1. kubectl exec cassandra -- cat /var/log/cassandra/system.log

You can run a shell that’s connected to your terminal using the -i and -t arguments to kubectl exec, for example:

  1. kubectl exec -it cassandra -- sh

For more details, see Get a Shell to a Running Container.

Debugging with an ephemeral debug container

FEATURE STATE: Kubernetes v1.23 [beta]

Ephemeral containers are useful for interactive troubleshooting when kubectl exec is insufficient because a container has crashed or a container image doesn’t include debugging utilities, such as with distroless images.

Example debugging using ephemeral containers

You can use the kubectl debug command to add ephemeral containers to a running Pod. First, create a pod for the example:

  1. kubectl run ephemeral-demo --image=k8s.gcr.io/pause:3.1 --restart=Never

The examples in this section use the pause container image because it does not contain debugging utilities, but this method works with all container images.

If you attempt to use kubectl exec to create a shell you will see an error because there is no shell in this container image.

  1. kubectl exec -it ephemeral-demo -- sh
  1. OCI runtime exec failed: exec failed: container_linux.go:346: starting container process caused "exec: \"sh\": executable file not found in $PATH": unknown

You can instead add a debugging container using kubectl debug. If you specify the -i/--interactive argument, kubectl will automatically attach to the console of the Ephemeral Container.

  1. kubectl debug -it ephemeral-demo --image=busybox --target=ephemeral-demo
  1. Defaulting debug container name to debugger-8xzrl.
  2. If you don't see a command prompt, try pressing enter.
  3. / #

This command adds a new busybox container and attaches to it. The --target parameter targets the process namespace of another container. It’s necessary here because kubectl run does not enable process namespace sharing in the pod it creates.

Note: The --target parameter must be supported by the Container Runtime. When not supported, the Ephemeral Container may not be started, or it may be started with an isolated process namespace so that ps does not reveal processes in other containers.

You can view the state of the newly created ephemeral container using kubectl describe:

  1. kubectl describe pod ephemeral-demo
  1. ...
  2. Ephemeral Containers:
  3.   debugger-8xzrl:
  4.     Container ID:   docker://b888f9adfd15bd5739fefaa39e1df4dd3c617b9902082b1cfdc29c4028ffb2eb
  5.     Image:          busybox
  6.     Image ID:       docker-pullable://busybox@sha256:1828edd60c5efd34b2bf5dd3282ec0cc04d47b2ff9caa0b6d4f07a21d1c08084
  7.     Port:           <none>
  8.     Host Port:      <none>
  9.     State:          Running
  10.       Started:      Wed, 12 Feb 2020 14:25:42 +0100
  11.     Ready:          False
  12.     Restart Count:  0
  13.     Environment:    <none>
  14.     Mounts:         <none>
  15. ...

Use kubectl delete to remove the Pod when you’re finished:

  1. kubectl delete pod ephemeral-demo

Debugging using a copy of the Pod

Sometimes Pod configuration options make it difficult to troubleshoot in certain situations. For example, you can’t run kubectl exec to troubleshoot your container if your container image does not include a shell or if your application crashes on startup. In these situations you can use kubectl debug to create a copy of the Pod with configuration values changed to aid debugging.

Copying a Pod while adding a new container

Adding a new container can be useful when your application is running but not behaving as you expect and you’d like to add additional troubleshooting utilities to the Pod.

For example, maybe your application’s container images are built on busybox but you need debugging utilities not included in busybox. You can simulate this scenario using kubectl run:

  1. kubectl run myapp --image=busybox --restart=Never -- sleep 1d

Run this command to create a copy of myapp named myapp-debug that adds a new Ubuntu container for debugging:

  1. kubectl debug myapp -it --image=ubuntu --share-processes --copy-to=myapp-debug
  1. Defaulting debug container name to debugger-w7xmf.
  2. If you don't see a command prompt, try pressing enter.
  3. root@myapp-debug:/#

Note:

  • kubectl debug automatically generates a container name if you don’t choose one using the --container flag.
  • The -i flag causes kubectl debug to attach to the new container by default. You can prevent this by specifying --attach=false. If your session becomes disconnected you can reattach using kubectl attach.
  • The --share-processes allows the containers in this Pod to see processes from the other containers in the Pod. For more information about how this works, see Share Process Namespace between Containers in a Pod.

Don’t forget to clean up the debugging Pod when you’re finished with it:

  1. kubectl delete pod myapp myapp-debug

Copying a Pod while changing its command

Sometimes it’s useful to change the command for a container, for example to add a debugging flag or because the application is crashing.

To simulate a crashing application, use kubectl run to create a container that immediately exits:

  1. kubectl run --image=busybox myapp -- false

You can see using kubectl describe pod myapp that this container is crashing:

  1. Containers:
  2.   myapp:
  3.     Image:         busybox
  4.     ...
  5.     Args:
  6.       false
  7.     State:          Waiting
  8.       Reason:       CrashLoopBackOff
  9.     Last State:     Terminated
  10.       Reason:       Error
  11.       Exit Code:    1

You can use kubectl debug to create a copy of this Pod with the command changed to an interactive shell:

  1. kubectl debug myapp -it --copy-to=myapp-debug --container=myapp -- sh
  1. If you don't see a command prompt, try pressing enter.
  2. / #

Now you have an interactive shell that you can use to perform tasks like checking filesystem paths or running the container command manually.

Note:

  • To change the command of a specific container you must specify its name using --container or kubectl debug will instead create a new container to run the command you specified.
  • The -i flag causes kubectl debug to attach to the container by default. You can prevent this by specifying --attach=false. If your session becomes disconnected you can reattach using kubectl attach.

Don’t forget to clean up the debugging Pod when you’re finished with it:

  1. kubectl delete pod myapp myapp-debug

Copying a Pod while changing container images

In some situations you may want to change a misbehaving Pod from its normal production container images to an image containing a debugging build or additional utilities.

As an example, create a Pod using kubectl run:

  1. kubectl run myapp --image=busybox --restart=Never -- sleep 1d

Now use kubectl debug to make a copy and change its container image to ubuntu:

  1. kubectl debug myapp --copy-to=myapp-debug --set-image=*=ubuntu

The syntax of --set-image uses the same container_name=image syntax as kubectl set image. *=ubuntu means change the image of all containers to ubuntu.

Don’t forget to clean up the debugging Pod when you’re finished with it:

  1. kubectl delete pod myapp myapp-debug

Debugging via a shell on the node

If none of these approaches work, you can find the Node on which the Pod is running and create a privileged Pod running in the host namespaces. To create an interactive shell on a node using kubectl debug, run:

  1. kubectl debug node/mynode -it --image=ubuntu
  1. Creating debugging pod node-debugger-mynode-pdx84 with container debugger on node mynode.
  2. If you don't see a command prompt, try pressing enter.
  3. root@ek8s:/#

When creating a debugging session on a node, keep in mind that:

  • kubectl debug automatically generates the name of the new Pod based on the name of the Node.
  • The container runs in the host IPC, Network, and PID namespaces.
  • The root filesystem of the Node will be mounted at /host.

Don’t forget to clean up the debugging Pod when you’re finished with it:

  1. kubectl delete pod node-debugger-mynode-pdx84