kubectl exec -it POD -- sh fails when the application image does not contain sh. To troubleshoot without rebuilding or restarting that container, use kubectl debug to add a separate ephemeral container with its own shell and tools. It can sometimes see the target container’s processes, but that depends on Pod namespace configuration and container-runtime support; it does not add a shell to the application image or guarantee access to its filesystem.
Why kubectl exec -- sh fails
Distroless runtime images contain an application and its runtime dependencies, but omit shells and the usual distribution utilities. If the image has no sh executable, kubectl exec -it POD -- sh has nothing to launch. That is a limitation of the image contents, not a special restriction imposed by kubectl exec. The Distroless project describes these images as containing only the application and runtime dependencies.
As an Amazon Associate I earn from qualifying purchases.
Kubernetes identifies this as a use case for ephemeral containers: interactive troubleshooting when kubectl exec is insufficient because an image lacks debugging utilities. The feature has been Stable since Kubernetes v1.25, according to the Kubernetes documentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
Start a shell in an ephemeral debug container
An ephemeral container is a separate container added to an existing Pod for troubleshooting. It has its own image, filesystem, shell, and diagnostic utilities. The application container remains the same; the debug container does not install a shell into it.
#1 Best Overall
kubectl debug -it POD --image=busybox --target=APP_CONTAINERReplace POD with the Pod name and APP_CONTAINER with the application container’s name. Choose a debug image that actually contains the shell and utilities you need. In this command, --image selects that image, while --target requests targeting the named container’s namespaces. Kubernetes documents this pattern in its running-Pod debugging guide.
The Distroless project also publishes :debug image variants that include a BusyBox shell. Those variants can be useful when building or testing a debug image; they are distinct from adding an ephemeral container to an already-running Pod.
What the debug container can—and cannot—see
Processes: possible, not guaranteed
--target asks the runtime to place the debug container in the target container’s namespaces so that tools such as ps may show its processes. Kubernetes says this targeting depends on container-runtime support. Without that support, the debug container may fail to start or may start with an isolated process namespace, leaving the target’s processes invisible.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchCheck the Pod’s process-namespace setup and the runtime’s behavior before treating an empty process listing as evidence that the application is not running. Process visibility is conditional, not a guarantee of the command.
Rank #3
Files and internal state: no automatic access
The debug container has its own filesystem and toolset. The documented workflow provides a troubleshooting environment; it does not promise that the target container’s complete filesystem or internal state becomes available. Do not assume that adding an ephemeral container mounts the application’s files into it.
Capabilities: constrained by the Pod’s security configuration
Tools and permissions depend on the debug image, the container configuration and the Pod’s security context. Kubernetes notes that some debug-profile capabilities may not work when the entire target Pod is configured to run as a non-root user. A profile does not automatically bypass the Pod’s security settings.
When to choose another debugging mode
| Method | Where it runs | What changes | Useful distinction |
|---|---|---|---|
| Ephemeral container | Inside the existing Pod | Adds a separate troubleshooting container | Keeps the Pod under investigation; process visibility depends on namespace and runtime support. |
| Pod copy | In a separate copied Pod | Creates another Pod with selected changes, such as a different image or command | Useful when changing the troubleshooting environment; it is not the same running Pod. |
| Node debugging | In a debugging Pod using the node’s host namespaces | Mounts the host filesystem at /host |
For node-level investigation rather than inspecting only an application container. |
These modes and their options are described in the Kubernetes debugging guide. Use a Pod copy when the original Pod should remain untouched or when a changed image or command is needed. Use node debugging when the problem is at the node level.
Recommended Free Tools
Know the limits before adding an ephemeral container
Ephemeral containers are intended for troubleshooting, not ordinary application workloads. Kubernetes documents several operational limits:
- They do not have automatic restart guarantees.
- Once added, they cannot be changed or removed.
- They cannot specify fields such as ports, liveness or readiness probes, or resource requests; Pod resource allocations are immutable.
- They are not supported for static Pods.
Check the Kubernetes documentation and the behavior of your cluster’s actual kubectl release and container runtime before relying on a particular targeting or profile capability.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
