8.15 Kubernetes Ephemeral Container Usage

Kubernetes Ephemeral Container Usage is the practice of temporarily injecting a special-purpose container into an already-running Pod to inspect, debug, or troubleshoot it, without needing to restart the Pod or modify its original specification.

Purpose and Characteristics

Debugging Running Workloads

Ephemeral containers exist primarily to support debugging scenarios in which the original application image lacks shell utilities, networking tools, or other diagnostic binaries, which is common in minimal or distroless production images. Rather than rebuilding the image with debug tools baked in, an operator can attach a fully equipped debug image directly to the live Pod.

No Guarantees on Resources or Restart

Unlike application and init containers, ephemeral containers have no resource requests or limits, are never automatically restarted, and are not included when Kubernetes computes a Pod's Quality of Service class. They are explicitly excluded from the normal Pod lifecycle guarantees because they are meant to be transient.

Immutable Once Added

An ephemeral container, once added to a running Pod via the ephemeralcontainers subresource, cannot be removed or modified. The only way to eliminate it is to delete and recreate the Pod itself, which reflects its intended use as a short-lived diagnostic aid rather than a permanent part of the workload.

How Ephemeral Containers Are Added

The Debug Subresource

Ephemeral containers are added through the Pod's ephemeralcontainers subresource, most commonly invoked through a command such as kubectl debug, which constructs the necessary API request and attaches an interactive session to the new container automatically.

Sharing Namespaces with Target Containers

An ephemeral container can be configured to share the process namespace of an existing container in the Pod using targetContainerName, which allows tools like ps, strace, or top running inside the ephemeral container to observe and interact with processes belonging to the target container.

Network and Volume Visibility

Because an ephemeral container is injected into the same Pod, it automatically shares the Pod's network namespace, meaning it can observe the same IP address and open sockets. It can also mount any volumes already defined in the Pod, giving direct access to persisted or shared data used by the running application.

Common Debugging Scenarios

Investigating a Crash Looping Container

When an application container repeatedly crashes before an operator can attach an interactive shell, an ephemeral container sharing the same process namespace can be used to inspect logs, open file descriptors, or leftover state from the failing process.

Network Connectivity Diagnosis

An ephemeral container equipped with tools such as curl, dig, or tcpdump can be attached to a Pod experiencing service discovery or connectivity failures, allowing the operator to test DNS resolution or capture traffic from within the exact network namespace the application uses.

Filesystem Inspection

An ephemeral container can mount the same volumes as the application container to inspect configuration files, logs, or corrupted data directly, without needing to copy files out of the Pod through the original container's limited toolset.

Limitations

Not Suitable for Production Traffic

Ephemeral containers are not intended to serve application traffic and have no mechanism for readiness or liveness integration with Services, so they should never be relied upon as part of a Pod's normal serving capacity.

Feature Availability

Support for ephemeral containers depends on the Kubernetes API server and kubelet version, and the feature historically required an alpha or beta feature gate to be enabled before becoming generally available in stable Kubernetes releases.