Debugging with kubectl debug in Kubernetes - Step-by-Step Execution

Process Flow - Debugging with kubectl debug

Identify Pod to Debug

↓

Run kubectl debug command

↓

Create Ephemeral Debug Container

↓

Attach to Debug Container

↓

Run Debugging Commands

↓

Exit Debug Container

↓

Ephemeral Container Removed Automatically

This flow shows how kubectl debug creates a temporary container inside a pod for troubleshooting, lets you run commands, then cleans up automatically.

Execution Sample

Kubernetes

kubectl debug pod/myapp-pod -it --image=busybox
# Runs a debug container inside myapp-pod
# Attach to it interactively

This command starts an interactive debug container inside the existing pod 'myapp-pod' using the busybox image.

Process Table

Step	Action	kubectl Command	Result	Notes
1	Identify Pod to debug	kubectl get pods	Pod 'myapp-pod' found	User selects pod to debug
2	Run debug container	kubectl debug pod/myapp-pod -it --image=busybox	Ephemeral container created and attached	Debug container runs inside pod
3	Run commands inside debug container	sh	Shell prompt inside debug container	User can run troubleshooting commands
4	Exit debug container	exit	Debug container terminates	Ephemeral container removed automatically
5	Verify pod state	kubectl get pods	Pod 'myapp-pod' running normally	No lasting changes to pod

💡 Debug container exits and is removed after user finishes debugging

Status Tracker

Variable	Start	After Step 2	After Step 4	Final
Pod State	Running with original containers	Running with ephemeral debug container added	Running with debug container removed	Running with original containers
Debug Container	Not present	Created and running	Terminated and removed	Not present

Key Moments - 3 Insights

Why does the debug container disappear after I exit?

The debug container is ephemeral, meaning it only exists during the debug session. As shown in execution_table step 4, when you exit, Kubernetes automatically removes it to keep the pod clean.

Can I change the pod's main containers using kubectl debug?

No, kubectl debug adds a temporary container alongside existing ones without modifying them. The pod state in variable_tracker confirms original containers stay unchanged.

What if the pod is not found when running kubectl debug?

You must first identify the correct pod name using 'kubectl get pods' as in execution_table step 1. If the pod name is wrong, debug cannot start.

Visual Quiz - 3 Questions

Look at the execution_table, what happens at step 2?

A An ephemeral debug container is created and attached

B The pod is deleted

C The main container restarts

D The debug container exits

💡 Hint

Refer to execution_table row 2 under 'Result' column

At which step does the debug container get removed?

A Step 1

B Step 3

C Step 4

D Step 5

💡 Hint

Check execution_table step 4 'Result' column for container termination

If you run 'kubectl debug' on a non-existing pod, what must you do first?

A Create a new pod

B Use 'kubectl get pods' to find the correct pod name

C Restart the cluster

D Run debug without pod name

💡 Hint

See key_moments question 3 about identifying pods

Concept Snapshot

kubectl debug lets you add a temporary container inside a running pod
Use: kubectl debug pod/<pod-name> -it --image=<image>
This container is ephemeral and removed after exit
Allows interactive troubleshooting without changing pod
Pod's original containers stay unchanged

Full Transcript

Debugging with kubectl debug means adding a temporary container inside a running pod to troubleshoot. First, you find the pod name with 'kubectl get pods'. Then you run 'kubectl debug pod/myapp-pod -it --image=busybox' to create and attach to a debug container. Inside, you can run commands like a shell. When done, exiting removes the debug container automatically. The original pod containers remain unchanged throughout. This method helps fix issues without restarting or changing the pod permanently.