Understanding kubectl describe vs docker inspect in Kubernetes

When you're troubleshooting Kubernetes Pods, it's common to ask: "Should I run kubectl describe or go into the node and run docker inspect?" While both commands are incredibly useful, they serve different purposes and offer insights from two different layers of the Kubernetes stack.

In this article, we’ll break down the difference between kubectl describe and docker inspect so you can confidently use the right tool at the right time.

---

kubectl describe pod <pod-name>: The Kubernetes View

kubectl describe shows you Kubernetes-level information about the resource (in this case, a pod).

What You Get:

• Metadata: Labels, annotations, namespace

• Pod status: Pending, Running, CrashLoopBackOff, etc.

• Node where the pod is scheduled

• Container specs: Image, ports, environment variables, volume mounts

• Events: Scheduling issues, failed image pulls, restarts, etc.

Use Cases:

• Investigate why a pod is failing to start

• Check the node a pod is scheduled on

• View readiness/liveness probe configurations

• See Kubernetes events tied to the pod

Think of this as: "What Kubernetes knows and manages about this pod."

---

docker inspect <container-id>: The Container Runtime View

Once a pod is running, its containers are managed by a container runtime (Docker, containerd, or CRI-O). docker inspect provides runtime-level details about the container.

What You Get:

• Process ID (PID) and cgroup details

• Network namespace and IP addresses

• File system mount points

• Environment variables as seen by the container

• Volumes and host path bindings

Use Cases:

• Debug container-level issues (e.g., missing mounts or misconfigured env vars)

• Inspect how Kubernetes translated your spec into runtime options

• Verify what is actually running inside the container

Think of this as: "What the container engine (like Docker) knows about this specific container."

---

One Pod, Multiple Containers

Remember: a Kubernetes Pod can have multiple containers. On the node, you’ll see:

• A pause container (used to maintain the pod's network namespace)

• One or more application containers

Each of these containers has its own container ID and needs to be inspected individually.

---

Quick Comparison Table

---

What if You’re Not Using Docker?

If you're using containerd or CRI-O (which is common in modern clusters), you’ll use tools like:

• crictl inspect <container-id>

• ctr containers info <container-id>

These provide the same kind of low-level detail as docker inspect, but for other runtimes.

---

Conclusion

Both kubectl describe and docker inspect (or its equivalents) are powerful tools in the Kubernetes debugging toolbox.

• Use kubectl describe when you want to understand how Kubernetes views your pod.

• Use docker inspect when you need to dig into what’s actually running on the node.

Mastering the difference will make you a more effective Kubernetes troubleshooter. 🚀

---

Happy debugging! 😊