Debugging with kubectl debug in Kubernetes - Commands & Configuration

Introduction

Sometimes your application in Kubernetes has problems and you need to look inside the running container to find out what is wrong. The kubectl debug command helps you create a temporary copy of the pod with extra tools to check what is happening.

When your pod is crashing and you want to inspect logs and files inside the container.

When you need to run troubleshooting commands inside a pod that does not have debugging tools installed.

When you want to test changes or commands in a copy of a running pod without affecting the original.

When you want to attach a debugging container to a running pod to check network or file system issues.

When you want to quickly get a shell inside a pod for manual inspection.

Commands

This command creates a temporary debugging pod based on 'my-pod' but uses the 'busybox' image which has useful debugging tools. The -it flags open an interactive terminal so you can run commands inside.

Terminal

kubectl debug -it my-pod --image=busybox --target=my-pod

Expected Output

If you are connected successfully, you will see a shell prompt like:

/ #

→

-i - Keep stdin open for interactive commands

→

-t - Allocate a pseudo-TTY for the terminal

→

--image - Specify the image to use for the debug container

→

--target - Specify the target pod to debug

Check that the debug pod was created and is running alongside the original pod.

Terminal

kubectl get pods

Expected Output

NAME              READY   STATUS    RESTARTS   AGE

my-pod            1/1     Running   0          10m

my-pod-debug      1/1     Running   0          1m

After finishing debugging, delete the temporary debug pod to clean up resources.

Terminal

kubectl delete pod my-pod-debug

Expected Output

pod "my-pod-debug" deleted

Key Concept

If you remember nothing else from this pattern, remember: kubectl debug lets you create a temporary pod with debugging tools to safely inspect and troubleshoot your running application.

Common Mistakes

Running kubectl debug without specifying --image for a pod that lacks debugging tools

The debug container will not have the tools you need, so you cannot troubleshoot effectively.

Always specify a debug image like busybox or ubuntu that has the tools you need using --image.

Not using -it flags when you want an interactive shell

Without -it, you won't get a usable terminal to run commands interactively.

Use both -i and -t flags together to open an interactive terminal session.

Forgetting to delete the debug pod after finishing

The debug pod will keep running and consume resources unnecessarily.

Run kubectl delete pod on the debug pod to clean up.

Summary

Use kubectl debug with --image and -it flags to create a temporary pod with debugging tools.

Check the debug pod status with kubectl get pods to ensure it is running.

Delete the debug pod after troubleshooting to free resources.