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.

Practice

1. What is the main purpose of the kubectl debug command in Kubernetes?

easy

A. To delete a pod and recreate it with debug options

B. To permanently change the pod's container image

C. To scale the number of pod replicas for debugging

D. To add a temporary container with debugging tools to a running pod

Solution

1. Step 1: Understand the purpose of kubectl debug

   This command adds a temporary container to a running pod for debugging without changing the original pod.

2. Step 2: Compare other options

   Options A, B, and D describe permanent or unrelated actions, not the temporary debugging feature.

3. Final Answer:

   To add a temporary container with debugging tools to a running pod -> Option D

4. Quick Check:

   Temporary debug container = C [OK]

Hint: Remember: debug adds temporary tools, no permanent pod change [OK]

Common Mistakes:

• Thinking debug changes pod image permanently
• Confusing debug with pod scaling
• Assuming debug deletes pods

2. Which of the following is the correct syntax to start a debug session on a pod named webapp-123?

easy

A. kubectl debug --pod webapp-123 --image=busybox

B. kubectl debug webapp-123 -image=busybox

C. kubectl debug pod/webapp-123 --image=busybox

D. kubectl debug pod webapp-123 --image=busybox

Solution

1. Step 1: Recall correct kubectl debug syntax

   The correct syntax uses kubectl debug pod/NAME --image=IMAGE to specify the pod and debug container image.

2. Step 2: Analyze options

   kubectl debug pod/webapp-123 --image=busybox matches the correct syntax exactly. Options A, B, and C have syntax errors or missing slashes.

3. Final Answer:

   kubectl debug pod/webapp-123 --image=busybox -> Option C

4. Quick Check:

   Correct syntax includes 'pod/' prefix = D [OK]

Hint: Use 'pod/NAME' format with --image option for debug [OK]

Common Mistakes:

• Omitting 'pod/' prefix before pod name
• Using spaces instead of slash between 'pod' and name
• Misplacing --image option

3. What will be the output of this command if the pod api-server-1 does not exist?

kubectl debug pod/api-server-1 --image=busybox

medium

A. Error: pods "api-server-1" not found

B. A new debug container starts successfully

C. Pod is deleted and recreated with debug image

D. Command runs but no debug container is added

Solution

1. Step 1: Understand pod existence requirement

   The kubectl debug command requires the target pod to exist to add a debug container.

2. Step 2: Predict command behavior if pod missing

   If the pod does not exist, kubectl returns an error indicating the pod was not found.

3. Final Answer:

   Error: pods "api-server-1" not found -> Option A

4. Quick Check:

   Missing pod causes 'not found' error = A [OK]

Hint: Check pod exists before debug; else 'not found' error [OK]

Common Mistakes:

• Assuming debug creates pod if missing
• Expecting debug to run silently without pod
• Confusing debug with pod creation commands

4. You run kubectl debug pod/myapp --image=busybox but get an error: error: container busybox not found. What is the likely cause?

medium

A. The debug container image is missing or misspelled

B. The pod does not exist

C. The pod already has a container named busybox

D. kubectl debug requires root privileges

Solution

1. Step 1: Analyze the error message

   The error says 'container busybox not found', which usually means the image name is incorrect or missing.

2. Step 2: Check common causes

   The debug container image is missing or misspelled fits because a misspelled or missing image causes this error. The pod existence or privileges are unrelated.

3. Final Answer:

   The debug container image is missing or misspelled -> Option A

4. Quick Check:

   Image name errors cause 'container not found' message [OK]

Hint: Verify debug image name spelling and availability [OK]

Common Mistakes:

• Assuming pod absence causes this error
• Thinking debug needs root privileges
• Confusing container name with image name

5. You want to debug a running pod backend-0 but need to run a shell with root privileges inside the debug container. Which command correctly achieves this?

hard

A. kubectl debug pod/backend-0 --image=busybox --target=backend-0 -- sh

B. kubectl debug pod/backend-0 --image=busybox --privileged -- sh

C. kubectl debug pod/backend-0 --image=busybox --container=debugger -- sh

D. kubectl debug pod/backend-0 --image=busybox --as-root -- sh

Solution

1. Step 1: Identify how to run debug container with root

   The --privileged flag allows the debug container to run with root privileges.

2. Step 2: Check command correctness

   kubectl debug pod/backend-0 --image=busybox --privileged -- sh uses --privileged and runs shell sh, which is correct. Other options misuse flags or do not enable root.

3. Final Answer:

   kubectl debug pod/backend-0 --image=busybox --privileged -- sh -> Option B

4. Quick Check:

   Use --privileged to get root shell in debug container [OK]

Hint: Add --privileged flag to run debug container as root [OK]

Common Mistakes:

• Using nonexistent flags like --as-root
• Confusing --target with privilege escalation
• Omitting --privileged when root shell needed