Ephemeral Containers

FEATURE STATE: Kubernetes v1.16alpha This feature is currently in a alpha state, meaning:

• The version names contain alpha (e.g. v1alpha1).
• Might be buggy. Enabling the feature may expose bugs. Disabled by default.
• Support for feature may be dropped at any time without notice.
• The API may change in incompatible ways in a later software release without notice.
• Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.

This page provides an overview of ephemeral containers: a special type of containerthat runs temporarily in an existing PodThe smallest and simplest Kubernetes object. A Pod represents a set of running containers on your cluster. to accomplish user-initiated actions suchas troubleshooting. You use ephemeral containers to inspect services rather thanto build applications.

Warning: Ephemeral containers are in early alpha state and are not suitable for production clusters. You should expect the feature not to work in some situations, such as when targeting the namespaces of a container. In accordance with the Kubernetes Deprecation Policy, this alpha feature could change significantly in the future or be removed entirely.

Understanding ephemeral containers

PodsThe smallest and simplest Kubernetes object. A Pod represents a set of running containers on your cluster. are the fundamental buildingblock of Kubernetes applications. Since Pods are intended to be disposable andreplaceable, you cannot add a container to a Pod once it has been created.Instead, you usually delete and replace Pods in a controlled fashion usingdeploymentsAn API object that manages a replicated application..

Sometimes it’s necessary to inspect the state of an existing Pod, however, forexample to troubleshoot a hard-to-reproduce bug. In these cases you can runan ephemeral container in an existing Pod to inspect its state and runarbitrary commands.

What is an ephemeral container?

Ephemeral containers differ from other containers in that they lack guaranteesfor resources or execution, and they will never be automatically restarted, sothey are not appropriate for building applications. Ephemeral containers aredescribed using the same ContainerSpec as regular containers, but many fieldsare incompatible and disallowed for ephemeral containers.

• Ephemeral containers may not have ports, so fields such as ports,livenessProbe, readinessProbe are disallowed.
• Pod resource allocations are immutable, so setting resources is disallowed.
• For a complete list of allowed fields, see the EphemeralContainer referencedocumentation.

Ephemeral containers are created using a special ephemeralcontainers handlerin the API rather than by adding them directly to pod.spec, so it’s notpossible to add an ephemeral container using kubectl edit.

Like regular containers, you may not change or remove an ephemeral containerafter you have added it to a Pod.

Uses for ephemeral containers

Ephemeral containers are useful for interactive troubleshooting when kubectl exec is insufficient because a container has crashed or a container imagedoesn’t include debugging utilities.

In particular, distroless imagesenable you to deploy minimal container images that reduce attack surfaceand exposure to bugs and vulnerabilities. Since distroless images do not include ashell or any debugging utilities, it’s difficult to troubleshoot distrolessimages using kubectl exec alone.

When using ephemeral containers, it’s helpful to enable process namespacesharing soyou can view processes in other containers.

Examples

Note: The examples in this section require the EphemeralContainers feature gate to be enabled and kubernetes client and server version v1.16 or later.

The examples in this section demonstrate how ephemeral containers appear inthe API. Users would normally use a kubectl plugin for troubleshooting thatwould automate these steps.

Ephemeral containers are created using the ephemeralcontainers subresourceof Pod, which can be demonstrated using kubectl —raw. First describethe ephemeral container to add as an EphemeralContainers list:

{
    "apiVersion": "v1",
    "kind": "EphemeralContainers",
    "metadata": {
            "name": "example-pod"
    },
    "ephemeralContainers": [{
        "command": [
            "sh"
        ],
        "image": "busybox",
        "imagePullPolicy": "IfNotPresent",
        "name": "debugger",
        "stdin": true,
        "tty": true,
        "terminationMessagePolicy": "File"
    }]
}

To update the ephemeral containers of the already running example-pod:

kubectl replace --raw /api/v1/namespaces/default/pods/example-pod/ephemeralcontainers  -f ec.json

This will return the new list of ephemeral containers:

{
   "kind":"EphemeralContainers",
   "apiVersion":"v1",
   "metadata":{
      "name":"example-pod",
      "namespace":"default",
      "selfLink":"/api/v1/namespaces/default/pods/example-pod/ephemeralcontainers",
      "uid":"a14a6d9b-62f2-4119-9d8e-e2ed6bc3a47c",
      "resourceVersion":"15886",
      "creationTimestamp":"2019-08-29T06:41:42Z"
   },
   "ephemeralContainers":[
      {
         "name":"debugger",
         "image":"busybox",
         "command":[
            "sh"
         ],
         "resources":{
         },
         "terminationMessagePolicy":"File",
         "imagePullPolicy":"IfNotPresent",
         "stdin":true,
         "tty":true
      }
   ]
}

You can view the state of the newly created ephemeral container using kubectl describe:

kubectl describe pod example-pod

...
Ephemeral Containers:
  debugger:
    Container ID:  docker://cf81908f149e7e9213d3c3644eda55c72efaff67652a2685c1146f0ce151e80f
    Image:         busybox
    Image ID:      docker-pullable://busybox@sha256:9f1003c480699be56815db0f8146ad2e22efea85129b5b5983d0e0fb52d9ab70
    Port:          <none>
    Host Port:     <none>
    Command:
      sh
    State:          Running
      Started:      Thu, 29 Aug 2019 06:42:21 +0000
    Ready:          False
    Restart Count:  0
    Environment:    <none>
    Mounts:         <none>
...

You can attach to the new ephemeral container using kubectl attach:

kubectl attach -it example-pod -c debugger

If process namespace sharing is enabled, you can see processes from all the containers in that Pod.For example, after attaching, you run ps in the debugger container:

ps auxww

The output is similar to:

PID   USER     TIME  COMMAND
    1 root      0:00 /pause
    6 root      0:00 nginx: master process nginx -g daemon off;
   11 101       0:00 nginx: worker process
   12 101       0:00 nginx: worker process
   13 101       0:00 nginx: worker process
   14 101       0:00 nginx: worker process
   15 101       0:00 nginx: worker process
   16 101       0:00 nginx: worker process
   17 101       0:00 nginx: worker process
   18 101       0:00 nginx: worker process
   19 root      0:00 /pause
   24 root      0:00 sh
   29 root      0:00 ps auxww

Feedback

Was this page helpful?

Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it onStack Overflow.Open an issue in the GitHub repo if you want toreport a problemorsuggest an improvement.