Before volumes make sense, you need to understand why containers lose their data in the first place.

A container is a running copy of a packaged application. The package is called an image. An image is a frozen, read-only bundle that holds your program and everything it needs. When a container starts, the system places a thin, writable layer on top of the image, and your program can create and change files there.

The catch is that this writable layer belongs to that one container only. When the container stops and a new one starts, Kubernetes builds a fresh container from the original image. The new container gets a brand new, empty writable layer. The old layer, along with everything you saved in it, is thrown away.

Three problems volumes solve

A volume is a directory, defined at the pod level, that containers can mount and use like a normal folder.

In Kubernetes, a volume is a folder that is declared as part of a pod, and then mounted into one or more containers at a path you choose. To mount means to attach a folder so that it appears at a certain location inside the container. From the application’s point of view, it is an ordinary folder. It reads and writes files the way it always does. The magic is in where those files really live and how long they last.

There are two steps to using a volume. First, the pod declares the volume and says what kind it is. Second, each container that wants to use it mounts it at a path. Different containers in the same pod can mount the same volume at different paths, and both see the same files.

flowchart TD
    A["Container restarts"] --> B["Container filesystem is lost"]
    A --> C["emptyDir data survives"]
    A --> D["Persistent volume data survives"]
    E["Pod is deleted"] --> F["Container filesystem is lost"]
    E --> G["emptyDir data is lost"]
    E --> H["Persistent volume data survives"]
    

Read the diagram carefully, because it holds the most important idea in this whole guide. Data can live at three different levels. The container’s own filesystem dies with the container. A pod-level scratch volume, called emptyDir, survives container restarts but dies with the pod. A persistent volume survives even when the pod is deleted.

What it is, why it exists, where it is used

What it is: a pod-level folder that containers mount and use.

Why it exists: containers are disposable, but data often is not. Volumes separate the life of the data from the life of the container.

Where it is used: databases, message queues, file uploads, machine learning datasets, shared caches, configuration delivery, secrets, and log collection.

A few basic words will make everything that follows easier to read.

Kubernetes is a system that runs containers across many machines and keeps them healthy. You describe what you want, and Kubernetes makes it happen and keeps it that way. Here are the parts that matter for storage.

Two more ideas: stateless and stateful

A stateless application keeps nothing important between requests. A simple website that shows the same page to everyone is stateless. If a copy disappears, another copy can take over without anyone noticing.

A stateful application remembers things. A database remembers rows. A queue remembers messages that have not been processed. If such an application loses its memory, real damage happens. Stateful applications are the main reason persistent volumes exist.

Storage in Kubernetes is teamwork between the control plane, the node, and the storage system.

The diagram below shows the main players. On the left, the control plane makes decisions and keeps records. In the middle, a worker node runs the pod and prepares the volume. On the right, a real storage system holds the bytes.

flowchart LR
    subgraph CP["Control Plane"]
        API["API Server"]
        PVCtl["Volume controller"]
        Sched["Scheduler"]
    end
    subgraph Node["Worker Node"]
        Kubelet["kubelet"]
        CSINode["CSI node plugin"]
        subgraph Pod["Pod"]
            C1["App container"]
            C2["Sidecar container"]
        end
        Vol["Mounted volume folder"]
    end
    subgraph Storage["Storage System"]
        Disk["Network disk or file share"]
    end
    API --> PVCtl
    API --> Sched
    Kubelet -.->|watches pod specs| API
    Kubelet --> CSINode
    CSINode --> Vol
    C1 --> Vol
    C2 --> Vol
    Vol --> Disk
    

Meet the components

Not all volumes are meant to last. Many are simply convenient folders that vanish with the pod.

An ephemeral volume is one whose life is tied to the pod. It appears when the pod starts and disappears when the pod is removed. These are the workhorses of everyday Kubernetes, and beginners meet them first.

emptyDir: the shared scratch folder

The emptyDir volume is the simplest type. It starts as an empty folder on the node when the pod is placed there. Every container in the pod can mount it. If a container crashes and restarts, the folder and its files are still there. If the pod is deleted, the folder is deleted too.

By default an emptyDir uses the node’s ordinary disk. You can instead ask for it to live in the node’s memory, which makes it very fast. Memory-backed folders are counted against the container’s memory limit, so a runaway program can fill memory and get stopped. You can also set a size limit so a single pod cannot swallow the whole disk.

configMap, secret, downwardAPI, and projected

Some volume types do not store user data at all. They deliver information into files.

Generic ephemeral volumes

Sometimes you want temporary storage that is bigger or faster than what the node offers, or that comes from a particular storage class. A generic ephemeral volume creates a real claim on a real storage system when the pod is created, and removes it when the pod is deleted. It is the best of both worlds: the scale of network storage with the tidy life of a scratch folder.

Sometimes storage is a folder or drive on the node itself. This is fast and simple, and full of sharp edges.

hostPath: borrowing a folder from the node

A hostPath volume mounts a file or folder from the node’s own filesystem straight into the pod. It is easy to understand: the pod sees a folder that really exists on the machine. It is popular for quick experiments and for system-level tools that must look at the node itself, such as agents that read logs from the machine.

But it has serious drawbacks. If the pod moves to a different node, it sees a different folder, so the data seems to vanish. Pods running with a hostPath can read or even change important files on the node, which is a security risk. Because of these dangers, hostPath is discouraged for ordinary application data.

local volumes: a safer way to use a node’s disk

A local volume also uses a disk attached to a specific node, but it is a proper persistent volume with a built-in rule: it can only be used on the node where the disk lives. Kubernetes knows this and places the pod on that node. Local volumes are prized for their speed, because the data does not cross a network. The trade-off is that if the node dies, the data is trapped on it until the node returns.

Persistent storage in Kubernetes uses two objects that beginners often mix up. Once you see the reason for the split, they become easy.

Kubernetes separates the people who provide storage from the people who use storage. Cluster administrators, or automated systems, create PersistentVolumes. Application developers create PersistentVolumeClaims. Kubernetes then matches them.

flowchart LR
    Pod["Pod"] -->|mounts| Claim["PersistentVolumeClaim"]
    Claim -->|bound to| Vol["PersistentVolume"]
    Claim -->|asks for a class| SC["StorageClass"]
    SC -->|creates through| Prov["CSI provisioner"]
    Prov --> Vol
    Vol --> Disk["Real disk in the storage system"]
    

How binding works

When a claim is created, Kubernetes looks for a volume that satisfies it. The volume must be at least as large as the request, must support the requested access mode, and must belong to the requested storage class. When a match is found, the two are bound together, one to one. No other claim can use that volume while the binding lasts. If no match exists and a storage class allows it, Kubernetes creates a new volume automatically, which is the topic of the next chapter.

Why the pod talks to the claim, not the volume

This indirection is deliberate. A developer’s pod description says only, “I need the claim named data.” It does not mention a cloud, a disk type, or a server address. The same pod description can then run on a laptop cluster with simple local storage, and in a large cloud cluster with fast replicated disks. Only the claim’s resolution changes. This makes applications portable.

Instead of hand-making every disk, modern clusters create them on demand.

In the early days, an administrator had to create volumes in advance and hope that they matched what developers later asked for. This is called static provisioning, and it still exists. Today most clusters use dynamic provisioning: when a claim arrives, the system creates a fitting disk on the spot.

The tool that makes this possible is the StorageClass. It is a menu of storage choices, such as “fast”, “cheap”, or “replicated”. Each entry says which driver creates the disk and with what settings. A claim picks a class by name. If the claim names none, the cluster’s default class is used, if one exists.

What a StorageClass decides

Why “wait for first consumer” matters

Many cloud disks live in one specific zone, which is a separate building or area within a region. If a disk is created immediately in zone A, but the scheduler later places the pod in zone B, the pod can never use the disk. The pod is stuck.

The wait-for-first-consumer mode fixes this. Kubernetes waits until a pod that uses the claim has been scheduled. Only then does it create the disk, in the same zone as the chosen node. Disk and pod always end up together. For zone-bound storage this is nearly always the right choice.

sequenceDiagram
    participant U as Developer
    participant A as API Server
    participant S as Scheduler
    participant P as Provisioner
    participant T as Attacher
    participant K as kubelet
    participant D as Storage System
    U->>A: Submit claim and pod
    S->>A: Choose Node A for the pod
    P->>D: Create a new disk in the same zone
    P->>A: Create volume and bind the claim
    T->>D: Attach the disk to Node A
    K->>D: Find the disk on Node A
    K->>K: Format if new, then mount
    K->>K: Place the folder inside the container
    K->>A: Report pod running
    

Two settings decide who may use a volume at the same time and what shape the storage takes.

Access modes: who can share it?

An access mode describes how many nodes or pods may use a volume at once and whether they may write. The names look scary, but the ideas are simple.

Volume modes: files or raw blocks?

Most volumes use filesystem mode. Kubernetes formats the disk with a filesystem and mounts a folder. The application sees files and directories. Some specialized programs, such as certain databases, prefer to manage the raw disk on their own. For them Kubernetes offers block mode, which hands over the raw device with no filesystem on it. Beginners should stay with filesystem mode.

The Container Storage Interface, or CSI, is the plug that lets any storage system work with Kubernetes.

Early versions of Kubernetes had storage code for every supported system built directly into the core. Every new storage vendor had to change Kubernetes itself, and every bug fix had to wait for a new Kubernetes release. This did not scale.

The answer was a standard called the Container Storage Interface. It defines a common set of requests, such as “create a volume”, “attach it to a node”, and “mount it here”. Any storage vendor can write a CSI driver that understands these requests. Kubernetes talks to the driver in the standard language, and the driver translates to its own system. The older built-in storage plugins have largely been moved over to CSI drivers.

The two halves of a driver

Helper programs called sidecars

Kubernetes ships a small set of helper programs that sit beside the driver and translate Kubernetes events into CSI requests. Each has one clear job.

• The provisioner watches for new claims and asks the driver to create disks.
• The attacher asks the driver to connect disks to nodes.
• The resizer grows volumes when a claim asks for more space.
• The snapshotter takes point-in-time copies.
• The node registrar tells the kubelet on each node that the driver is present.

Between “the pod is scheduled” and “the app can write a file”, a careful sequence of steps takes place.

A pod cannot start its containers until its volumes are ready. The kubelet on the chosen node waits for each volume to be prepared, and only then lets the containers begin. Here is the journey for a persistent network disk, told in order.

Cleaning up in reverse

When the pod ends, the steps happen in reverse. The container stops, the pod’s private folder is unmounted, the staging mount is removed if no other pod on the node needs it, and the disk is detached from the node. Only then can another node attach the same disk. If the node dies unexpectedly, this reverse process cannot happen cleanly, and the disk may remain attached to a dead machine for a while. This is a classic source of stuck pods, covered in the troubleshooting chapter.

Volumes and claims move through named states, and knowing them makes error messages readable.

stateDiagram-v2
    [*] --> Available
    Available --> Bound: Claim matches
    Bound --> Released: Claim deleted
    Released --> Available: Admin clears it for reuse
    Released --> Deleted: Reclaim policy Delete
    Released --> Failed: Cleanup problem
    Deleted --> [*]
    

What happens when you delete a claim?

This is the most important safety question in Kubernetes storage, and the answer is decided by the reclaim policy.

Protection against accidental deletion

Kubernetes adds a safety net called storage object in use protection. If you delete a claim that a running pod is still using, the deletion is postponed until the pod stops. The same guard protects volumes that are still bound. This prevents the ugly case of pulling a disk out from under a running application.

When you run several copies of a stateful application, each copy needs its own private, stable storage.

A normal Deployment gives every pod identical everything, and pods are interchangeable. That is perfect for web servers. But consider a database cluster with three members. Each member holds its own data and must keep its identity across restarts. Member number two must come back as member number two, with member number two’s data.

The StatefulSet was designed for this. It gives each pod a stable name, such as db-0, db-1, and db-2, and a stable network identity. It also lets you define a volume claim template: a recipe for a claim. Kubernetes uses the recipe to make one separate claim per pod. Pod db-0 always reattaches to db-0’s claim, no matter which node it lands on.

What happens when you scale down or delete

By default, Kubernetes does not delete the claims when a StatefulSet is scaled down or removed. This is deliberate: your data is precious, and a cautious default protects you. The claims stay behind until you delete them yourself. Newer Kubernetes versions add a retention policy setting, so you can choose to have claims cleaned up automatically when you are sure that is what you want.

Data grows and mistakes happen. Kubernetes has tools for both.

Expanding a volume

If a disk fills up, you do not need to create a bigger one and copy everything. When the storage class allows expansion, you simply edit the claim and request a larger size. The driver grows the disk, and the filesystem is enlarged to match. Many drivers can do this while the pod keeps running. There is one firm rule: volumes can grow but they cannot shrink.

Snapshots

A snapshot is a frozen picture of a volume at one moment. It works like a photograph of a document: later changes to the document do not alter the photo. Kubernetes models snapshots with three objects. A snapshot class describes how to take them. A snapshot request asks for one. A snapshot content object records the real snapshot in the storage system. The storage driver must support snapshots for this to work.

Snapshots are quick and usually space-efficient because they record only changes. They are excellent for protecting against mistakes, such as a bad software update that corrupts data. They are not a full backup on their own, because many snapshots live inside the same storage system as the original disk. If that system is lost, both are lost.

Cloning

A clone makes a new volume that starts with a copy of an existing one. You create a new claim and point it at the source. Clones are handy for testing an upgrade on a copy of production data, or for spinning up a developer environment that starts with realistic contents.

Storage speed is measured in three ways, and choosing the wrong one to worry about is a common error.

A database doing many tiny lookups cares mostly about IOPS and latency. A program copying huge video files cares mostly about throughput. A disk that is excellent at one may be mediocre at another, so first understand what your application really does.

Local versus network storage

Network disks, such as those offered by cloud providers, are convenient and can move between machines, but every read and write crosses a network. That adds delay. Local disks attached directly to the machine are much faster, but they tie the pod to the machine. Many production databases accept the network delay in return for easier recovery, while others use local disks and rely on replication between members for safety.

Limits to watch

A volume that cannot be reached, or that has been lost, is worse than no volume at all.

Zones and the trapped disk

Most cloud block disks live in a single zone. If that zone has an outage, the disk is unreachable, and any pod that needs it cannot start elsewhere. This surprises many teams who thought “Kubernetes will move my pod to another zone.” It will try, but the disk cannot follow.

There are three common ways to deal with this. You can replicate data at the application level, so that each database member in a different zone holds its own full copy. You can use storage that spans zones, such as certain regional disks or managed file services. Or you can accept a period of downtime and restore from a backup into a healthy zone.

Two numbers every team should know

The recovery point objective is how much recent data you can afford to lose, measured in time. If it is fifteen minutes, your backups or replicas must never be older than that. The recovery time objective is how long you can afford to be down. If it is one hour, your restore process must reliably finish within the hour. These two numbers, not technology preferences, should drive your storage design.

Backups that actually work

Tools built for Kubernetes can back up both the cluster’s descriptions and the contents of volumes, and store them in a separate place, such as object storage in another region. Whatever tool you use, remember the golden rule: a backup you have never restored is only a hope. Schedule regular test restores into a separate environment and check that the application starts and the data looks right.

Volumes can hold your most sensitive data, and they can also be a doorway into the node itself.

Secrets in volumes

Secret volumes are held in memory on the node, so they never touch the disk, which reduces the chance of leaks. Still, any container that mounts a secret can read it. Mount secrets only into containers that need them, and prefer short-lived credentials that rotate. For service identity, Kubernetes delivers time-limited tokens through projected volumes, which are far safer than long-lived passwords sitting in files.

Data lifecycle and privacy

When a disk is deleted or reused, the storage system should ensure old data cannot be read by the next user. Reputable cloud disks do this for you. For local disks and retained volumes that an administrator reuses, cleaning the disk is a step you must not skip, especially when the data was personal or regulated.

Full disks and stuck mounts are among the most common causes of night-time alerts. Watch for them early.

Alerts worth setting up

• A claim more than eighty percent full, with a stronger alert above ninety percent.
• A claim pending longer than a few minutes.
• Repeated mount or attach failures for the same pod.
• Volumes in a Released or Failed state that nobody has handled.
• Sudden growth in disk usage, which often signals a runaway log or a bug.
• Backup jobs that have not succeeded within their expected window.

Volumes give you power over your data. That power comes with responsibilities.

Block, file, and object storage compared

A short set of questions leads you to the right choice in nearly every case.

flowchart TD
    Start["Need storage for a pod"] --> Q1{"Must data survive pod deletion?"}
    Q1 -->|No| Q2{"Scratch space or configuration?"}
    Q2 -->|Scratch| ED["Use emptyDir"]
    Q2 -->|Config or secret| CFG["Use configMap or secret volume"]
    Q1 -->|Yes| Q3{"Many pods write at once?"}
    Q3 -->|Yes| RWX["Use shared file storage with ReadWriteMany"]
    Q3 -->|No| Q4{"Speed on one node matters most?"}
    Q4 -->|Yes| LOC["Consider a local volume with care"]
    Q4 -->|No| BLK["Use a network block volume with ReadWriteOnce"]
    

Notice that most durable, single-writer cases end at a network block volume. That is why it is the everyday choice for databases in Kubernetes. Shared file storage is the answer when several pods on different nodes must write to the same place, such as an upload folder for a website. Scratch space and configuration have their own simple types, which you should always use in preference to durable disks for temporary needs.

Some volume habits age well. Others cause data loss.

Patterns that work

Anti-patterns to avoid

A handful of habits prevents most storage disasters.

Best practices

Common mistakes

The same ideas appear on every major platform, under different product names.

Most storage problems fall into a few well-known shapes. Work from the claim outward.

Quick answers to the questions beginners ask most often.