Storage declared inside the Pod itself, with a life that matches the Pod.

A volume in Kubernetes is a folder that a container can read and write. Containers by themselves have a private filesystem that disappears when the container restarts, so volumes exist to give containers somewhere to keep files that must survive a restart, be shared between containers, or come from outside. Volumes come in two big families. Persistent volumes outlive any Pod and keep data for as long as you want. Ephemeral volumes live and die with the Pod that uses them.

The word inline describes how the volume is declared. An inline volume is written directly inside the Pod’s specification, in the same file as the containers. You do not need to create a separate object ahead of time, ask an administrator for a claim, or clean up afterward. You describe the volume next to the container that uses it, and Kubernetes does the rest. When the Pod is deleted, the volume goes with it.

The four main kinds in one sentence each

The simple emptyDir gives a blank folder on the node. The configMap, secret, downwardAPI, and projected volumes fill a folder with configuration or identity data. The CSI ephemeral volume asks a storage driver to prepare a folder, with driver-specific options written inline. The generic ephemeral volume asks Kubernetes to create a real, dynamically provisioned storage claim for the Pod and delete it afterwards.

Containers are born with an empty, private, short-lived filesystem. Real programs need more than that.

When a container starts, it gets a thin writable layer on top of its image. This layer is private to the container, is lost when the container is recreated, and is usually slower and less controlled than a proper volume. For many jobs, that is not enough. Let us look at the common needs one by one.

Why not just use persistent volumes for everything?

A persistent volume needs a separate object, a claim, which someone must create, name, and delete. If a job creates a thousand claims and forgets to delete them, you pay for a thousand idle disks. Persistent volumes also tie a workload to a specific piece of storage, which makes scaling and rescheduling harder. For temporary data, all of this ceremony is wasted effort. Ephemeral volumes remove the paperwork by letting the Pod itself carry the storage request.

Twelve short words that you will meet in every storage conversation.

Do not confuse these two similar names

An ephemeral volume is storage that lives with a Pod. An ephemeral container is a completely different feature: a temporary debugging container that you attach to a running Pod. They share a word, not a purpose. Whenever you read “ephemeral” in Kubernetes, check which of the two is meant.

A map of the choices before we explore each one in depth.

flowchart TB
  POD["Pod specification"] --> ED["emptyDir"]
  POD --> CFG["configMap, secret, downwardAPI, projected"]
  POD --> CSI["CSI ephemeral inline volume"]
  POD --> GEN["Generic ephemeral volume"]
  POD --> PVC["PersistentVolumeClaim reference"]
  ED --> N1["Folder on node disk or in memory"]
  CFG --> N2["Files filled by the kubelet from API objects"]
  CSI --> N3["Folder prepared by a CSI driver on the node"]
  GEN --> N4["Real claim created and deleted with the Pod"]
  PVC --> N5["Persistent storage that outlives the Pod"]
    

The simplest ephemeral volume, and by far the most common.

An emptyDir volume starts as a blank folder, created when the Pod is assigned to a node. Every container in the Pod can read and write it, so it is also the standard way to share files between containers in one Pod. If a container crashes and restarts, the folder and its contents remain, because the Pod is still alive. The folder is deleted for good only when the Pod is removed from the node for any reason: deletion, eviction, or node loss.

Disk-backed versus memory-backed

By default, an emptyDir uses the node’s disk. You can ask for the memory medium instead, which creates a tmpfs, a filesystem held in RAM. It is very fast and never written to disk, which makes it good for small sensitive files and for latency-sensitive caches. But memory is scarce, and everything written there counts against the container’s memory limit. A runaway program filling a memory-backed emptyDir can cause the container to be killed for using too much memory.

The size limit

An emptyDir can have a size limit. For the memory medium, the limit shapes the size of the tmpfs. For the disk medium, the limit is checked periodically by the kubelet, and if the Pod’s use exceeds it, the Pod is evicted. This is not instant, so a fast writer can briefly overshoot before the check catches it.

Volumes that the kubelet fills with data from the Kubernetes API.

How they stay up to date

These volumes are different from emptyDir because the kubelet keeps them in sync with the source objects. If you edit a ConfigMap, the files in running Pods change after a short delay, which depends on the kubelet’s refresh period and cache. The kubelet updates files atomically, so a program never reads a half-written file. There is one important exception: if a container mounts a single file from such a volume using a sub-path, that file is not updated. Programs that must pick up changes should mount the whole folder and watch for changes.

Projected service account tokens

A very important use of projected volumes is the service account token. Pods use it to prove their identity to the Kubernetes API or to other systems. A projected token has a short, configurable lifetime, is limited to a chosen audience, and is automatically refreshed by the kubelet before it expires. It is also bound to the Pod, so it becomes invalid when the Pod is deleted. This is much safer than the old long-lived tokens that never expired.

Node disks are finite. Kubernetes keeps accounts so that one noisy Pod cannot fill them.

On every node, Kubernetes tracks a resource called ephemeral storage. It covers three things a Pod can use on the node’s local disk: the writable layer of its containers, the logs its containers produce, and the disk-backed emptyDir volumes. You can put a request and a limit on this resource for each container, just as you do for CPU and memory. The request helps the scheduler find a node with enough room. The limit protects the node by letting the kubelet evict a Pod that uses too much.

What gets evicted first

When a node runs low on disk, the kubelet first tries to reclaim space by cleaning unused images and dead containers. If that is not enough, it evicts Pods. It chooses Pods that exceed their requests for the scarce resource first, and among those, lower priority Pods go before higher priority ones. A Pod that stays within its requests is the last to be chosen. The evicted Pod shows a message saying that its ephemeral local storage usage exceeds the limit, or that the node was low on resources.

A storage driver prepares a folder for your Pod, on request, using options you write directly in the Pod.

A CSI ephemeral volume uses the Container Storage Interface to let a driver prepare a folder for a single Pod. The Pod names the driver and supplies a set of free-form options, called volume attributes, whose meaning is up to the driver. There is no claim, no storage class, and no separate object. The volume exists only in the Pod specification, which is why it is called inline. This feature became generally available in Kubernetes 1.25.

sequenceDiagram
  participant U as User
  participant API as API Server
  participant S as Scheduler
  participant K as Kubelet
  participant D as CSI node driver
  U->>API: Create Pod with an inline CSI volume
  API-->>S: Watch event for unscheduled Pod
  S->>API: Bind Pod to a node
  API-->>K: Watch event for Pod on this node
  K->>D: NodePublishVolume with the volume attributes
  D->>D: Prepare the folder and mount it
  D-->>K: Volume ready
  K->>K: Start containers with the volume mounted
  Note over K,D: When the Pod ends the kubelet calls NodeUnpublishVolume
    

What inline CSI volumes cannot do

Because only the node part of the driver is used, many storage features are unavailable. There is no storage class, no size request in the usual sense, no snapshots, no cloning, no resizing, and no capacity-aware scheduling. They are best seen as a way for a driver to hand a specially prepared folder to a Pod, not as a general purpose disk.

Every CSI driver describes itself to the cluster through a small object that controls how the kubelet treats it.

Why the pod info setting matters

An inline volume has no object of its own to carry identity. Without the Pod’s name, namespace, and service account, a driver would not know whom it is serving. With the pod info setting turned on, the driver receives these details on every publish call and can look up the right secret, issue the right certificate, or enforce the right access rule.

Rotation without restart

Certificates and secrets expire or are rotated. Restarting every Pod for each rotation would be disruptive. With the republish feature, the driver is called again periodically with the same inputs and may update the files in the existing folder. The application reads the new files without a restart, as long as it knows to re-read them. This is how secrets from vaults can stay fresh in long-running Pods.

The most powerful ephemeral type: any storage system that supports dynamic provisioning can supply per-Pod storage.

A generic ephemeral volume lets you put a claim template right inside the Pod. It looks like the template used in a StatefulSet, but the result is tied to the Pod’s life. When the Pod is created, a controller creates a real PersistentVolumeClaim from the template, owned by the Pod. The usual storage machinery then provisions a real volume. When the Pod is deleted, the claim is deleted along with it, and the storage is released according to the rules of its storage class. This feature became generally available in Kubernetes 1.23.

sequenceDiagram
  participant U as User
  participant API as API Server
  participant EC as Ephemeral volume controller
  participant S as Scheduler
  participant P as CSI provisioner
  participant K as Kubelet
  U->>API: Create Pod with a claim template
  API-->>EC: Watch event for the new Pod
  EC->>API: Create PVC owned by the Pod
  API-->>S: Pod waits for its claim
  S->>API: Choose node and mark claim for that node
  API-->>P: Watch event for the claim
  P->>P: Create the volume on that node or zone
  P->>API: Create PV and bind the claim
  API-->>K: Pod can start on its node
  K->>K: Attach, mount and start containers
  Note over API,EC: When the Pod is deleted the claim is garbage collected
    

The fine print that decides whether these volumes behave well in a real cluster.

Naming and conflicts

The claim created for a Pod is named by joining the Pod name and the volume name with a dash. This keeps names predictable, and ensures that each Pod has its own claim. If a claim with that name already exists and is not owned by the Pod, the controller refuses to take it over, and the Pod will not start. This protects other people’s data, but can be confusing if someone created a claim by hand with the same name.

Ownership and cleanup

The claim carries an owner reference pointing to the Pod. The Kubernetes garbage collector deletes objects whose owner is gone, so the claim is removed after the Pod. If a Pod is force-deleted, the claim is still cleaned up later by the garbage collector. The storage class’s reclaim policy matters here: with the common delete policy, the underlying disk is deleted with the claim. With a retain policy, the disk stays behind and must be cleaned manually, which can quietly cost money.

Why wait-for-first-consumer is almost always right

If a claim is bound immediately, the provisioner has to guess where to create the disk. For local storage or zonal cloud disks, a wrong guess means the disk is in one zone while the Pod is scheduled in another, and the Pod cannot start. Waiting for the scheduler to choose a node first means the disk is created where the Pod will actually run. For ephemeral volumes, which are created together with the Pod, this is the natural choice.

The lifecycle of the claim

stateDiagram-v2
  [*] --> Created
  Created --> Pending: Claim exists and waits for a node
  Pending --> Bound: Provisioner creates the volume
  Bound --> InUse: Pod starts and mounts it
  InUse --> Terminating: Pod is deleted
  Terminating --> Released: Claim removed by garbage collection
  Released --> [*]: Volume deleted or retained by policy
    

Five questions lead to the right volume nearly every time.

flowchart TD
  A["What do you need?"] --> B{"Must data outlive the Pod?"}
  B -->|"Yes"| P["Use a PersistentVolumeClaim"]
  B -->|"No"| C{"Is it configuration, a secret or Pod info?"}
  C -->|"Yes"| D["Use configMap, secret, downwardAPI or projected"]
  C -->|"No"| E{"Does a special driver prepare it, for example a vault or certificate?"}
  E -->|"Yes"| F["Use a CSI inline ephemeral volume"]
  E -->|"No"| G{"Need large size, special speed, snapshots or quotas?"}
  G -->|"Yes"| H["Use a generic ephemeral volume"]
  G -->|"No"| I["Use emptyDir, with a size limit"]
    

Image volumes: a newer relative

A newer Kubernetes feature, the image volume, lets a Pod mount the contents of a container image or artifact as a read-only folder. It is useful for delivering large, read-only data such as machine learning model files, separately from the application image. It has been progressing through preview stages in recent releases, so check the status in your version before depending on it. It complements the other types because the data arrives already prepared, with the same caching and distribution as container images.

Each type has a different start-up cost and a different effect on the cluster.

Where the time goes for a generic ephemeral volume

By definition, ephemeral data is lost with the Pod. The goal is to make the loss harmless and the recovery quick.

flowchart TD
  A["Pod stuck in ContainerCreating or Pending"] --> B{"Is there a FailedMount event?"}
  B -->|"Yes"| B1["Check CSI driver Pods on that node, driver name and attributes"]
  B -->|"No"| C{"Is the claim Pending?"}
  C -->|"Yes"| C1["Check storage class, provisioner logs, quota and zone capacity"]
  C -->|"No"| D{"Was the Pod evicted?"}
  D -->|"Yes"| D1["Check ephemeral storage limits, logs and emptyDir sizes"]
  D -->|"No"| E["Check node health, attach limits and scheduler events"]
    

Designing for loss

Programs that use ephemeral volumes should assume the data can vanish at any moment. Caches should be able to rebuild themselves. Download steps should be repeatable. Results should be written to a permanent store as soon as they are ready, not left in the scratch area until the end. A job that writes ten hours of results to scratch space and uploads at the end loses everything if the Pod is evicted at hour nine.

Temporary does not mean harmless. Storage decisions are security decisions.

Controls to put in place

Disk problems are slow burns. Good measurement turns surprises into early warnings.

Events are the first place to look

When a Pod does not start because of storage, the describe output of the Pod shows events from the kubelet and the controllers. Messages such as a failed mount or a failed provisioning give a precise reason: a wrong driver name, a missing storage class, a quota exceeded, or no capacity in the zone. The exact text of the event usually tells you which team or component to contact.

Alerts that earn their keep

Ephemeral volumes are convenient, and convenience always has limits.

A few habits make ephemeral storage reliable. A few others cause late night pages.

Patterns worth copying

Anti-patterns to avoid

A short checklist to read before you add temporary storage to a Pod.

Mistakes beginners make

• Thinking emptyDir survives Pod replacement. It survives only container restarts within the same Pod.
• Forgetting that memory-backed folders use memory. The files count toward the container’s memory limit.
• Ignoring container logs and writable layers. They also count as ephemeral storage, and often cause the eviction.
• Creating a claim by hand with the same name as an ephemeral claim. The Pod will refuse to start.
• Using inline CSI with a driver that does not support it. Check the lifecycle modes of the driver first.
• Assuming ConfigMap changes appear instantly. There is a refresh delay, and sub-path mounts never update.
• Leaving the default storage class unchecked. A template with no class will use whatever the default is, which may be slow or expensive.

The same ideas appear again and again in production clusters.

Short answers to the questions beginners ask most often.

You started with a hotel room that is cleaned out at checkout and finished with a clear picture of how Kubernetes handles temporary storage. The simplest tool is emptyDir, a blank folder with the Pod’s life. Configuration and secrets arrive through configMap, secret, and projected volumes. When a driver must prepare the folder, CSI inline volumes step in. When you need a real, sized, quota-controlled disk that still vanishes with the Pod, generic ephemeral volumes create and delete a claim for you. The skill lies in choosing the lightest tool that fits, setting limits, designing for loss, and controlling who can use what.