How to Debug Google Distroless Images: A Zero-to-Hero Guide

This is the standard, no-redeployment method. It injects an ephemeral debug container into your running pod using Kubernetes Ephemeral Containers (requires Kubernetes 1.23+).

Why `--target` matters. Without it, your debug container runs in an isolated process namespace. You will only see its own processes. With --target=<container-name>, Kubernetes shares the target container's process namespace. Running ps aux inside the debug container now shows your app's processes.

Accessing the file system. Your app's files are not at /app inside the debug container. They live at:

The /proc/1/root path exposes the target container's entire filesystem through the kernel's process filesystem interface.

#🧪 Method 2: The Staging Way (:debug Tags)

Google publishes debug variants for every distroless image. These include a busybox shell and are meant for development or staging troubleshooting.

Change your image tag from:

To:

With the debug tag, the container includes a shell and you can exec normally:

The drawback: You must change the image and restart the pod. This requires a redeployment and is not suitable for live incident response. Never ship :debug tags to production.

#⚡ Method 3: The Power User Way (cdebug)

If the process namespace handling and /proc/1/root path feel error-prone under pressure, cdebug automates it.

cdebug automatically shares the process namespace and mounts the target filesystem to a predictable path, removing the manual steps from Method 1.

#✅ Summary Checklist

Three things to remember:

1. Use kubectl debug for live production issues - no redeployment required. 2. Use :debug tags for development and staging environments only.

3. Your app's files are at /proc/1/root, not at the path you expect inside the debug container.