Containers are built to be disposable, but many applications need to remember things. That mismatch is the problem CSI helps to solve.

Containers forget everything

A container is a sealed package that holds a program and everything it needs to run. When Kubernetes starts a container, it gets a fresh, private file area. When the container stops or crashes, that file area is thrown away, together with everything written into it. This is by design, because it makes containers easy to replace, copy, and move.

For a simple web page that only shows information, this is fine. But a database, a message queue, or an application that stores uploaded photos must keep its data safe even if its container is replaced. The data must live somewhere outside the container, and it must be able to follow the application wherever Kubernetes moves it.

Storage comes in many shapes

Real organisations use very different kinds of storage. Public clouds offer virtual disks that attach to one machine. Data centres offer shared file servers that many machines can use at once. Some teams run their own storage software across a set of servers. Others use expensive vendor storage arrays. Each of these has its own commands, its own way of creating a volume, and its own way of attaching it.

Without a common rule book, Kubernetes would have to learn every one of these systems separately, and every storage vendor would have to modify Kubernetes itself to be supported. That would make Kubernetes huge, slow to update, and fragile. CSI solves this by defining one agreed interface between Kubernetes and any storage system.

What applications need from storage

CSI is a published standard that describes how an orchestrator and a storage system talk to each other. A driver is a program that speaks this standard on behalf of one storage system.

The idea in plain words

The Container Storage Interface is a specification, which means a written set of rules. It says which requests a storage plugin must understand, such as “create a volume”, “delete a volume”, “attach this volume to that machine”, and “make a snapshot”. It also says what answers the plugin must give. The requests and answers use a common communication method called gRPC.

Anyone can write a program that follows these rules. That program is called a CSI driver. A storage vendor or a community project writes one driver for their storage system, and the same driver can work with any orchestrator that supports CSI. Kubernetes is the best known, but other systems use the same standard.

Why this design is powerful

Because drivers live outside Kubernetes, storage vendors can release updates on their own schedule, without waiting for a new Kubernetes version. Because the interface is standard, a team that moves from one cloud to another only needs to change which driver its storage class uses, and the application description stays the same. And because the code for each storage system no longer sits inside Kubernetes, the core project becomes smaller, safer, and easier to maintain.

The vocabulary you will use

CSI plugs into a set of Kubernetes objects that describe storage from the application’s point of view. Let us meet them before looking inside the driver.

Claims and volumes: the request and the reality

The most important pair to understand is the claim and the volume. A developer writes a claim, which says “I need twenty gigabytes of storage that one pod can write to”. The claim describes the need, not the source. The actual storage that satisfies it is described by a persistent volume. Kubernetes matches each claim to a suitable volume, and once matched, they are said to be bound.

This separation is deliberate. The developer never needs to know whether the storage is a cloud disk or a file server. The person managing the cluster decides which storage classes exist, and the developer simply picks one by name.

Storage classes: named recipes

A storage class is a recipe for making volumes. It names the driver that will do the work, and it carries settings such as the disk type, whether the data is encrypted, and what happens to the volume when it is no longer needed. A cluster often has several classes, for example one for fast solid-state disks and one for cheaper, slower storage.

Understanding what came before CSI explains why it was needed, and why so many clusters have gone through a migration.

In-tree plugins: storage code inside Kubernetes

In the early days, support for each storage system was written directly into the Kubernetes source code. These were called in-tree plugins, because they lived inside the main tree of code. There were plugins for the big cloud disks and for several file and block storage systems, all compiled into the same programs that made up Kubernetes.

This approach was simple at first, but it grew painful. A bug in one storage plugin could affect the whole system. Vendors had to wait for a Kubernetes release to ship a fix or a new feature. The project had to maintain code for dozens of systems it did not control. Security issues in any of it became security issues for Kubernetes itself.

FlexVolume: a first step outside

FlexVolume was an early attempt to move storage code out of the core. A vendor provided an executable file placed on every node, and the kubelet ran it to attach and mount volumes. This let vendors ship drivers independently, but it had real limits. The executable had to be installed on each host, it could not easily use the cluster’s own features, and it lacked support for many operations such as snapshots and resizing.

CSI: the lasting answer

CSI was created to give a proper, complete, and stable answer. It reached general availability in Kubernetes in late 2018. It runs drivers as ordinary containers, so they can be deployed, upgraded, and monitored the same way as any other application. It also defines a rich set of operations, so features like snapshots, cloning, expansion, and topology awareness became possible for every driver.

What the migration means for you

If you have older clusters that use the built-in cloud disk types, Kubernetes has been quietly translating those requests to the matching CSI driver. In recent versions, the old in-tree code is gone, and you must install the CSI driver yourself, or use a managed service that installs it for you. Existing volumes keep working, but you should learn which driver serves them and keep it up to date.

A CSI driver is not one program. It is a small team of containers, some running centrally and some on every node, each with a clear job.

Every CSI driver is made of two halves plus a simple identity check. The controller half handles jobs that concern the whole cluster, such as creating and deleting volumes and attaching them to machines. The node half runs on each machine and handles jobs that must happen locally, such as mounting a volume into a pod’s directory. Both halves are described in the diagram below.

flowchart LR
    K["Kubernetes control plane and kubelet"] --> S["Sidecars turn Kubernetes events into CSI calls"]
    S -->|"gRPC over a local socket"| D["CSI driver with controller and node plugins"]
    D --> B["Storage backend: cloud disk, file share, or storage array"]
        

Read the figure from left to right. Kubernetes does not talk to the driver directly. Small helper containers called sidecars watch Kubernetes for events, such as a new claim or a new attachment, and turn each event into a CSI request. They send the request to the driver over a local connection. The driver then talks to the real storage system, using whatever method that system understands.

The three services in every driver

The sidecar helpers

The Kubernetes community maintains a set of ready-made sidecar containers so that each driver author does not have to reinvent the watching logic. The driver author writes only the storage-specific part, and the sidecars do the rest. Each sidecar has a single responsibility.

flowchart TD
    subgraph CS["Controller side, run as a Deployment"]
        P["external-provisioner"] --> CP["Controller plugin"]
        A["external-attacher"] --> CP
        R["external-resizer"] --> CP
        SN["external-snapshotter"] --> CP
    end
    subgraph NS["Node side, run as a DaemonSet on every node"]
        N["node-driver-registrar"] --> NP["Node plugin"]
    end
        

Dynamic provisioning is what makes storage feel like a cloud service: you ask, and a volume appears. Here is what happens behind the scenes.

Static versus dynamic

In the older, static way, an administrator creates volumes by hand ahead of time and registers each one in Kubernetes. Developers then claim from that fixed pool. This works, but it needs a person for every volume and often wastes space, since the pre-made volumes rarely match what teams truly need.

In dynamic provisioning, nobody creates volumes in advance. A developer creates a claim that names a storage class. The system notices the claim, asks the driver to create a matching volume on demand, and binds the two together. The volume exists exactly when it is needed, and with exactly the size that was requested.

sequenceDiagram
    participant U as User
    participant A as API Server
    participant P as external-provisioner
    participant D as CSI Controller Plugin
    participant B as Storage Backend
    U->>A: Create a claim that names a storage class
    P->>A: Watch sees the new claim
    P->>D: CreateVolume request
    D->>B: Create the disk or share
    B-->>D: Volume identifier
    D-->>P: Volume created
    P->>A: Create the volume record and bind it to the claim
        

Waiting for the pod: the binding mode

A storage class has a setting called the volume binding mode. With the immediate mode, the volume is created as soon as the claim appears. The problem is that the system has not yet decided where the pod will run, so the volume may be created in a zone where the pod cannot use it.

With the wait-for-first-consumer mode, the system waits until a pod that uses the claim is scheduled to a machine. Only then does it create the volume, in a location that suits that machine. For any storage tied to a zone, such as a cloud disk, this is almost always the right choice.

Creating a volume is only the beginning. Before a container can read a single byte, the volume must travel through several more steps.

Three steps to get a volume ready

Once a pod that uses a bound claim is scheduled to a machine, three things must happen. First the volume must be attached, meaning connected to that machine, like plugging a disk into a computer. Second it must be staged, meaning prepared once on the machine: formatted if it is brand new, and mounted at a shared staging folder. Third it must be published, meaning made visible inside the specific pod’s own folder.

Staging and publishing are separate because several pods on the same machine may share one volume. The volume is staged once per machine, and then published once for each pod that uses it, usually with a lightweight bind mount, which is a way of showing the same folder in a second place.

sequenceDiagram
    participant K as Kubelet
    participant AC as external-attacher
    participant CD as Controller Plugin
    participant ND as Node Plugin
    participant B as Storage Backend
    Note over AC,CD: A pod is scheduled to a node
    AC->>CD: ControllerPublishVolume
    CD->>B: Attach the volume to the node
    K->>ND: NodeStageVolume
    ND->>ND: Format if new, mount at the staging path
    K->>ND: NodePublishVolume
    ND->>ND: Bind mount into the pod folder
    K->>K: Start the containers with the volume
        

Tearing it down again

When a pod stops, the steps run in reverse. The volume is unpublished from that pod, then unstaged from the machine if no other pod there still uses it, and finally detached from the machine by the driver. Only after detaching can the volume be attached elsewhere, if the pod is being moved.

When machines fail

The teardown order creates a well-known trap. Many volumes can be attached to only one machine at a time. If a machine dies suddenly, it cannot unstage or unpublish anything, so the volume may remain attached to the dead machine. A replacement pod on another machine is then stuck waiting, because the backend still believes the volume is in use elsewhere.

Kubernetes handles this with a timeout. After a period of several minutes, it forces the detach on machines that are unreachable, and the replacement pod can proceed. This delay is a real part of failure recovery, and it is why databases on single-attach disks do not fail over instantly.

Not all storage is alike. The type of storage decides who can use a volume, how many at once, and how the data looks to the application.

Block, file, and object storage

Access modes: who may use the volume

When a claim is created, it states an access mode. This describes how many machines or pods may use the volume, and whether they may write. The driver and the storage system decide which modes they can honestly support.

Volume modes: files or raw blocks

Most volumes are presented as a file system, meaning a folder tree that the application uses normally. Some specialised applications, such as certain databases, prefer to receive the raw block device directly and manage the layout themselves. Kubernetes supports both, called filesystem mode and block mode, and the driver must support the one requested.

A storage class is where a cluster’s storage decisions live. Understanding its settings lets you shape cost, speed, safety, and behaviour.

What a storage class contains

Reclaim policy: what happens to your data

The reclaim policy is one of the most important safety settings. With the delete policy, removing the claim removes the volume and its data from the storage system. This is convenient and clean, but it means an accidental deletion of a claim is an accidental deletion of data. With the retain policy, the volume and data are kept after the claim is gone, and an administrator must clean up or reuse it by hand.

Dynamically created volumes usually inherit the delete policy by default. For data that matters, many teams create a separate class with retain, and use it for production databases.

Topology: keeping volume and pod together

Many storage systems are tied to a location. A cloud disk in one zone cannot be attached to a machine in another zone. CSI drivers report the topology of each machine and each volume, and the scheduler uses this to keep pods and their volumes together. With wait-for-first-consumer binding, the volume is created in the zone where the pod was placed, so the two always match.

Because CSI defines a rich set of operations, drivers can offer much more than plain volumes. Here are the features that matter most in practice.

A volume has a whole life: it is requested, created, bound, used, released, and finally kept or deleted. Each stage has its own traps.

flowchart TD
    A["Claim created"] --> B{"Binding mode?"}
    B -->|"Immediate"| C["Volume created at once"]
    B -->|"WaitForFirstConsumer"| D["Wait until a pod is scheduled"]
    D --> C
    C --> E["Volume bound to claim"]
    E --> F["Pod uses the volume"]
    F --> G["Pod and claim deleted"]
    G --> H{"Reclaim policy?"}
    H -->|"Delete"| I["Volume and data removed"]
    H -->|"Retain"| J["Volume kept for manual recovery"]
        

The states a volume passes through

Protection against accidents

Kubernetes adds special markers called finalizers to volumes and claims that are in use. A finalizer blocks deletion until Kubernetes has finished its cleanup work. This prevents you from removing a claim while a pod still uses it. It also explains why a claim can appear stuck in a terminating state: something is still using it, or a cleanup step has not completed.

Storage holds your most valuable data, and CSI drivers run with powerful access. Security has to be designed in from the start.

A CSI driver has two sources of power. The controller side can create, delete, and attach volumes in your storage system, often using cloud permissions. The node side must mount file systems on the machine, so it runs with high privileges and deep access to the machine’s file layout. Both deserve careful control.

Leftover data is a risk

Volumes are reused and deleted, and old data may remain. When a volume is released with the retain policy and later reused, the previous owner’s data may still be there. When a volume is deleted, the backend may or may not wipe the underlying storage before reusing it. For sensitive data, know how your storage system handles deletion, and use encryption so that discarded data is unreadable.

Sharing volumes across tenants

Shared volumes used by several teams create a shared blast radius. A bug or compromise in one application can corrupt or expose data used by others. Where isolation matters, give each tenant its own volumes, and use quotas to keep one tenant from filling the whole storage system.

Storage problems are quiet until they are catastrophic. A full disk or a stuck attachment can halt an application with no warning, unless you are watching.

What to watch

Kubernetes and its add-ons publish many of these as metrics that monitoring tools can collect, including volume usage figures from the kubelet and the state of claims and volumes from the cluster’s state exporters. The sidecars also expose their own metrics about how many operations they performed and how long they took. Events on pods and claims give the human-readable story, and they are usually the first place to look.

Logs that help

When something goes wrong, three log sources tell the story. The logs of the driver and its sidecars show what requests were made and how the storage system answered. The kubelet log on the affected machine shows the mount and unmount steps. The storage provider’s own audit log shows what was actually done to the disks. Sending all three to a central store makes investigations much faster.

Untangling a stuck pod or claim

CSI solves a big problem, but running stateful applications on Kubernetes always comes with trade-offs worth understanding.

Thinking about cost honestly

Storage costs come from several places. There is the price of the disks or shares themselves, which is often charged for the size you ask for, not the size you use. There is the price of snapshots, which grow as data changes. There is the cost of performance, since faster storage classes cost more. And there is the cost of forgotten volumes, which continue to be billed even after the application that used them is gone.

The best defence is visibility. Track which volumes exist, who owns them, and how full they are. Use quotas to limit runaway requests, and choose storage classes deliberately, so cheap storage is used for cheap needs.

Choosing the right kind of storage

A few reliable designs cover most storage needs. A few tempting shortcuts cause most of the lost data.

Patterns that work well

Anti-patterns to avoid

A short field guide collected from teams that run stateful applications on Kubernetes, and from mistakes that repeat.

Best practices

• Know your driver — read its documentation for supported access modes, features, limits, and upgrade notes.
• Keep drivers updated — treat them like any critical component, with a plan for security and compatibility updates.
• Use wait-for-first-consumer binding — especially for zone-bound storage in multi-zone clusters.
• Enable expansion — allow volumes to grow, and practise the expansion before you need it in an emergency.
• Choose reclaim policies deliberately — use retain for data you cannot recreate.
• Set the default class on purpose — know what a claim gets when it names no class.
• Apply storage quotas — limit how much storage and how many claims each namespace can use.
• Encrypt sensitive data — use encrypted classes and manage keys with care.
• Back up outside the cluster — and test restores, because an untested backup is only a hope.
• Alert on fullness and pending claims — catch problems while there is still time to act calmly.
• Handle graceful shutdown — make sure applications flush data and close files when pods stop.
• Review orphaned volumes — periodically compare the storage system with the cluster to find forgotten volumes.

Common mistakes

CSI drivers exist for nearly every kind of storage, and organisations use them in very different ways.

Quick answers to the questions that come up most often when teams first work with CSI.

No. The driver is a separate program, usually run as containers in your cluster. Kubernetes only defines how to talk to it. Managed services often install common drivers for you.

A claim is a request for storage written by the application owner. A volume is the record of the actual storage. Kubernetes binds each claim to a matching volume.

Common reasons are a missing or misspelled class, a binding mode that waits for a pod, no capacity or wrong location in the backend, or a driver that is not running. The claim’s events usually say which.

No. Kubernetes supports growing volumes, not shrinking them. To reduce size, create a smaller volume and copy the data across.

The data stays, because it lives in the volume, not the pod. A new pod that uses the same claim sees the same data. The data is only removed when the claim and volume are deleted under a delete policy.

It depends on the access mode and the storage. Shared file storage supports many pods across many machines. Single-attach block disks allow sharing only among pods on the same machine, or only one pod with the strict mode.

No. Snapshots are usually kept in the same storage system and can be lost with it. Backups are stored elsewhere and should be tested by restoring them.

The volume may still be attached to the dead machine. Kubernetes waits for a timeout before forcing a detach, which can take several minutes. This is normal for single-attach storage.

Often the main disk driver is installed for you, but drivers for shared file storage or other systems may need to be added. Check your provider’s documentation.

It delays creating the volume until a pod that uses the claim has been scheduled, so the volume is created in the right location for that pod.

Not directly through Kubernetes objects. You usually copy the data by using backups, snapshots that the storage system can share, or a data copy tool, and then create a new claim in the target cluster.

Yes, many teams do, with proper volumes, backups, monitoring, and often a database operator. It needs care about failover time, performance, and recovery, so weigh it against managed database services.

The Container Storage Interface gives Kubernetes a single, standard way to work with almost any storage system. Developers describe what they need through claims and storage classes, and drivers translate those requests into the actions of a specific system. Each volume moves through provisioning, attaching, staging, publishing, use, and eventual release, and the sidecar helpers turn Kubernetes events into the requests the driver understands.

The standard is powerful but not magic. Features depend on the driver, single-attach volumes slow failover, snapshots are not backups, and the driver itself runs with high privileges. Teams that choose storage classes with care, watch capacity, protect their data outside the cluster, and keep drivers updated find that persistent storage on Kubernetes becomes dependable and routine.