Running Commands in Containers with `kubectl exec`

1. What is kubectl exec and When Should You Use It?

At a high level, kubectl exec allows you to run a command inside a specific container that is already running in a Pod. The Kubernetes API server facilitates a connection to the kubelet on the node hosting the Pod, which then interfaces with the container runtime (like Docker or containerd) to execute your command.

To understand the mechanics and common use cases, let's start with a foundational reading.

To summarize, you'll reach for kubectl exec when kubectl logs isn't enough. Common situations include:

• Inspecting the Environment: Verifying the contents of a configuration file that was mounted via a ConfigMap, or checking the values of environment variables.
• Testing Network Connectivity: Running ping or curl from inside the Pod to diagnose connectivity issues to other services within the cluster or to external endpoints. This is crucial for debugging network policies or service discovery problems.
• Running Diagnostic Tools: Using command-line tools that are bundled with your application image, such as a database client (psql, mysql) to connect to a database or a performance tool (top) to check resource usage.

2. Executing Commands: From One-Liners to Interactive Shells

Now for the practical part. There are two main ways to use kubectl exec: running a single, non-interactive command, or opening a persistent, interactive shell session.

Running a Single Command

The simplest use is to execute a command and see its output. The syntax is:

kubectl exec <pod-name> -- <command> [args...]

The double dash (--) is important. It separates the kubectl arguments from the command you want to run inside the container. Without it, kubectl might misinterpret arguments intended for your command as its own.

For example, to list the files in the /etc directory of a pod named api-gateway-xyz:

kubectl exec api-gateway-xyz -- ls -l /etc

Getting an Interactive Shell

This is the most powerful and common use case. It gives you a terminal session inside the container. For this, you need to use the -i (interactive, keeps STDIN open) and -t (allocates a pseudo-TTY) flags, almost always combined as -it.

The syntax is:

kubectl exec -it <pod-name> -- <shell-executable>

The shell executable is typically /bin/bash or, for many minimal container images (like those based on Alpine Linux), /bin/sh.

# Get a bash shell in the 'api-gateway-xyz' pod
kubectl exec -it api-gateway-xyz -- /bin/bash

# If bash isn't available, try sh
kubectl exec -it api-gateway-xyz -- /bin/sh

Once inside, you can run commands freely until you type exit or press Ctrl+D.

Let's watch a quick video demonstration to see this in action.

Dealing with Multi-Container Pods

Your experience with platforms like EKS and AKS means you'll eventually encounter Pods with multiple containers (e.g., an application container and a sidecar for service mesh proxy or log shipping). If you run kubectl exec on such a Pod without specifying a container, you'll get an error.

You must use the -c or --container flag to target the correct one.

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

For a deeper dive into the syntax variations, including the -c flag, the unyaml.com article is a great reference.

3. Best Practices and What to Avoid

While kubectl exec is a powerful debugging tool, it should be used judiciously. As a Platform Engineer, it's vital to understand that it's a manual intervention, not a standard administrative practice. Changes made via exec are ephemeral—they happen inside the container's filesystem and will be lost if the container restarts.

This final reading highlights the "do's and don'ts" of using kubectl exec.

Key principles to remember:

• Debug, Don't Administer: Use exec for inspection and diagnosis. If you need to change a file, the correct approach is to update the source (e.g., a ConfigMap or Docker image) and redeploy.
• Security is Paramount: Access to exec is a high-level privilege. In a production environment, this access is typically restricted using Role-Based Access Control (RBAC), a topic we will cover later.
• Expect Minimal Tools: Production container images are often stripped of all non-essential binaries to reduce size and attack surface. Don't be surprised if tools like curl, ping, or even bash are missing.

Conclusion

You have now added kubectl exec to your Kubernetes command-line toolkit. You understand not just how to use it, but more importantly, when and why to use it—and when not to. This skill bridges the gap between observing a Pod from the outside (describe, logs) and investigating its internal state directly.

Key Takeaways:

• kubectl exec runs commands inside a running container, similar to docker exec.
• Use -it to open an interactive shell (e.g., kubectl exec -it my-pod -- /bin/sh).
• For Pods with multiple containers, you must use the -c <container-name> flag to specify your target.
• exec is an essential tool for interactive debugging but should not be used for routine configuration or management, as any changes are ephemeral.

In our previous lessons, we've assembled a powerful set of tools: get to see status, describe to see events, logs to see application output, and now exec to go inside the container. In our next and final lesson of this module, we will put it all together to diagnose and resolve some of the most common Pod failure scenarios you'll encounter in the wild, such as ImagePullBackOff and CrashLoopBackOff.