Mastering kubectl exec: A Hands-On Guide for Kubernetes Troubleshooting

When you’re managing applications running inside Kubernetes pods, sometimes you need to get inside a container to troubleshoot, inspect, or run commands. That’s where kubectl exec becomes one of your most powerful tools.

In this blog, I’ll walk you through commonly used kubectl exec commands with real-world DevOps scenarios, best practices, and tips. Whether you’re debugging logs, checking memory, or connecting to a database inside your pod, this guide has you covered.

Basic Syntax

kubectl exec -it <pod-name> -- <command>

• -it: Combines -i (interactive) and -t (TTY), allowing you to interact with the shell.

• --: Separates kubectl arguments from the actual command you want to run inside the container.

Common kubectl exec Commands

1. Start a shell inside a pod

kubectl exec -it <pod-name> -- /bin/bash

Use this to open an interactive shell inside a pod. It’s useful for running multiple commands, just like on a VM.

• For Alpine or minimal containers:

kubectl exec -it <pod-name> -- /bin/sh

Use case:

Investigating why your app isn’t serving requests, or inspecting temporary file storage.

⸻

2. List files in a pod

kubectl exec <pod-name> -- ls -l /app

This lists files inside a specific directory of the container. Use it to verify if build artifacts or config files exist.

Use case:

Checking whether /etc/config/settings.yaml was mounted correctly from a ConfigMap.

——-

3. Check environment variables

   
   

kubectl exec <pod-name> -- printenv

This displays all environment variables set within the container.

Use case:

Troubleshooting misconfigured env vars or secrets.

⸻

4. View logs or config inside the container

kubectl exec <pod-name> -- cat /var/log/app.log

kubectl exec <pod-name> -- cat /etc/config/config.yaml

This allows you to inspect internal files for logs, configuration, or diagnostics.

Use case:

When an application fails and the logs aren’t streamed to kubectl logs.

⸻

5. Check running processes

kubectl exec <pod-name> -- ps aux

View all running processes in the container.

Use case:

Verify if your NodeJS or Python process is running as expected, or identify zombie processes.

⸻

6. Test network connectivity

kubectl exec <pod-name> -- ping google.com

kubectl exec <pod-name> -- curl http://<service-name>:<port>

These commands test external or internal service communication.

Use case:

Confirming that your pod can talk to an external API or internal microservice.

⸻

7. Run database queries

kubectl exec -it <pod-name> -- mysql -u root -p

kubectl exec -it <pod-name> -- psql -U postgres

Run MySQL or PostgreSQL shell commands from inside the pod.

Use case:

Querying table counts, checking DB health, verifying user permissions.

⸻

8. Check disk usage or memory

kubectl exec <pod-name> -- df -h

kubectl exec <pod-name> -- free -m

These commands give you disk and memory stats inside the pod.

Use case:

Diagnosing issues related to OOM (Out Of Memory) or storage exhaustion.

⸻

Advanced Tips

Target a specific container in a multi-container pod

kubectl exec -it <pod-name> -c <container-name> -- /bin/bash

Use with namespaces

kubectl exec -it <pod-name> -n <namespace> -- /bin/bash

Best Practices

1. Avoid running exec in production unless necessary. Use observability tools like Prometheus or logs instead.

2. Restrict exec permissions using Kubernetes RBAC—this can be a security risk.

3. Audit exec sessions if you’re in a sensitive environment (e.g., financial or healthcare systems).

⸻

Summary Cheat Sheet

Start shell

kubectl exec -it pod -- /bin/bash

List files

kubectl exec pod -- ls -l /app

Env vars

kubectl exec pod -- printenv

Read logs

kubectl exec pod -- cat /var/log/app.log

Check memory

kubectl exec pod -- free -m

Run MySQL

kubectl exec -it pod -- mysql -u root -p

Final Thoughts

kubectl exec is a critical tool in the Kubernetes troubleshooting toolkit. But it should be used wisely—it’s easy to cause unintentional damage in live environments. When combined with clear permissions, good observability, and responsible usage, it’s a powerful way to solve problems fast.