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.

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