Disk space is the one resource that almost always grows and almost never shrinks by itself.

Containers are designed to be disposable. When a container restarts, everything inside it vanishes, which is perfect for stateless web servers and terrible for databases, message queues, search indexes and anything else that must remember things. For those workloads, Kubernetes attaches persistent storage: a disk that lives outside the container and survives restarts, rescheduling and even node failures.

When you create that disk, you must choose its size, and you must choose it before you know how the application will behave. Pick too small, and the application runs out of room as data accumulates. Pick far too large, and you pay for empty space every month. Real data growth is rarely predictable. A marketing campaign doubles the number of customers, a new feature writes more logs, an index grows after a schema change, or a backup job leaves large temporary files behind. Sooner or later, almost every persistent volume needs to become bigger.

What happens when a volume fills up

The effects are rarely gentle. Databases may refuse writes or crash into recovery. Message brokers stop accepting messages. Applications that write logs to the volume may hang. Because the failure is often sudden and affects the busiest, most important systems, a full disk is one of the classic causes of night-time pages. Before expansion existed in Kubernetes, the fix usually meant creating a bigger volume, copying all the data across and switching over, which meant downtime and risk.

A short refresher on the four objects that every storage conversation depends on.

Expansion makes more sense once the cast of characters is clear. Kubernetes separates the person who needs storage from the machinery that provides it, and four ideas hold the picture together.

How a claim turns into a disk

With dynamic provisioning, an application owner creates a claim that names a storage class. A component watching the cluster notices the claim, asks the class’s CSI driver to create a disk of the requested size, and creates the matching volume object. The claim and the volume are then bound, and a Pod that mounts the claim sees a directory backed by that disk.

A request to grow, a pair of resizing steps, and a status that confirms the result.

Volume expansion is the ability to increase the size of an existing persistent volume claim, and therefore the real disk behind it, without recreating anything. The user experience is deliberately simple. You edit the claim and raise the storage amount in its requests. Everything after that is automatic.

Spec and status

Like most Kubernetes objects, a claim has a spec, which describes what you want, and a status, which describes what is real. The requested size lives in the spec. The size the cluster has actually provided lives in the status as capacity. When you raise the spec, the two values differ, and controllers work to bring the status up to match. When they match again, the expansion is done. This is the same declare-and-reconcile pattern that drives the rest of Kubernetes.

Growing is allowed, shrinking is not

Kubernetes only supports making volumes larger. Attempting to lower the requested size of a bound claim is rejected. There are practical reasons. Most filesystems cannot be shrunk safely while mounted, many cloud disks cannot be made smaller at all, and shrinking could destroy data if the used space exceeded the new size. If you ever need a smaller volume, you must create a new one and move the data, which Chapter 14 covers.

Three switches must all be on, or the request is refused.

Volume expansion is not automatically available for every claim. Three conditions must hold, and knowing them helps you diagnose the common case where an edit is rejected on the spot.

The admission check

Kubernetes runs a built-in admission step that examines every update to a claim. If the update raises the requested size and the class does not allow expansion, the update is refused immediately with a clear message. This is a fast, friendly failure, and it is the first thing to check when an expansion request is rejected.

The central idea of the whole topic: a bigger disk is not yet a bigger usable space.

A persistent volume has two layers that both have to grow. The lower layer is the disk itself, a block device provided by a cloud or storage system. The upper layer is the filesystem, the organised structure of directories and files written onto that disk. When the disk is made larger, the filesystem on it still thinks it occupies the old, smaller area. It must be told to stretch into the new space. Kubernetes therefore expands volumes in two separate phases.

flowchart TD
    A["User raises requested size on the claim"] --> B["Admission check: class allows expansion?"]
    B -->|No| X["Request rejected"]
    B -->|Yes| C["Controller expansion: storage backend enlarges the disk"]
    C --> D["Volume object capacity is raised"]
    D --> E{"Does the volume need a filesystem resize?"}
    E -->|No| G["Claim capacity updated, done"]
    E -->|Yes| F["Claim waits: filesystem resize pending"]
    F --> H["Node expansion: filesystem grows on the node"]
    H --> G
        

Why two phases exist

The two steps need different powers. Enlarging a cloud disk is an operation performed through the provider’s programming interface and needs no access to a particular node. Growing a filesystem, on the other hand, must be done where the volume is attached, because the operating system on that node owns the mount. Splitting the work this way lets each part run in the right place, and it explains why a claim can spend some time in a waiting state between the two.

A small team of programs cooperates to turn an edit into extra space.

Several pieces take part in an expansion. Knowing who is responsible for which step makes troubleshooting far easier, because you can ask which component has not done its job.

sequenceDiagram
    participant U as User
    participant API as API Server
    participant R as External Resizer
    participant D as CSI Controller Plugin
    participant S as Storage Backend
    participant K as Kubelet
    participant N as CSI Node Plugin
    U->>API: Raise requested size on the claim
    API->>API: Admission checks the class allows expansion
    R->>API: Notice requested size is larger than capacity
    R->>D: Expand this volume
    D->>S: Enlarge the disk
    S-->>D: Done
    D-->>R: New size, node expansion needed
    R->>API: Update volume capacity, mark filesystem resize pending
    K->>API: Notice pending filesystem resize
    K->>N: Expand the filesystem
    N-->>K: Done
    K->>API: Update claim capacity to the new size
        

How to read what is happening from the claim itself.

While an expansion is underway, the claim records its progress using conditions. A condition is a small piece of status that says something is true or in progress. Reading these conditions is the quickest way to know whether to wait or to investigate.

flowchart LR
    A["Steady: requested equals capacity"] -->|"User raises requested size"| B["Resizing: disk is being enlarged"]
    B -->|"Disk enlarged, filesystem needs growing"| C["Filesystem resize pending"]
    C -->|"Node grows the filesystem"| D["Steady again at the new size"]
    B -->|"Backend error"| E["Resize error recorded"]
    C -->|"Node error"| E
    E -->|"Cause fixed, retry succeeds"| B
        

The two size fields

Always compare two numbers on the claim: the size requested in the spec and the capacity reported in the status. While they differ, expansion is in progress or stuck. Recent Kubernetes versions also record how much space has been allocated and the status of each resize step, which helps tools and people see exactly how far an expansion has progressed, and supports recovery after a failed attempt.

Whether the application can keep running while its disk grows.

One of the most practical questions is whether a Pod must be stopped. Kubernetes supports expanding a volume while it is in use, which is called online expansion, and this has been a stable feature for several releases. Whether it works for your volume depends on the CSI driver and the filesystem. Some drivers can only complete the filesystem step when the volume is not in use, which is offline expansion, and in that case the filesystem grows the next time a Pod mounts the volume.

flowchart TD
    A["Disk has been enlarged"] --> B{"Does the driver support online filesystem growth?"}
    B -->|Yes| C["Kubelet grows the filesystem while the Pod keeps running"]
    B -->|No| D["Claim shows filesystem resize pending"]
    D --> E["Pod is stopped or restarted"]
    E --> F["Filesystem grows during the next mount"]
    C --> G["Expansion complete"]
    F --> G
        

What actually lives on the disk decides how the second phase behaves.

Most volumes in Kubernetes are mounted as filesystems. The two filesystems most often used are ext4 and XFS, and both can be grown while mounted, which is what makes online expansion possible. The node step of an expansion runs the right growing tool for whichever filesystem the volume contains. If the filesystem type is one that cannot be grown, the second phase cannot complete, even though the disk itself became larger.

Raw block mode

A volume can also be given to a Pod as a raw block device, with no filesystem at all. This is used by software that manages the disk directly, such as some databases and storage systems. Expansion enlarges the device, but nobody grows a filesystem, because none exists. The application itself must detect the larger device and extend its own structures. Kubernetes does the first half only.

Space is more than bytes

A filesystem has two limits: how many bytes of data it can hold and how many files it can track. The second is controlled by a pool of file records called inodes. A volume with millions of tiny files can run out of inodes long before it runs out of bytes. Growing a filesystem generally adds more inodes as well, so expansion helps with both problems, but it is wise to monitor both.

Not every kind of storage can be grown, and some do not even mean the same thing by size.

Kubernetes can attach many kinds of storage, and expansion support depends on the type. A rough map of the landscape helps set expectations.

The place where expansion stops being a one-line edit and needs a careful routine.

Databases and other stateful systems are usually run as StatefulSets. A StatefulSet creates one Pod per replica and, for each, a separate claim built from a volume claim template. This gives each replica its own persistent disk, which is exactly what a database cluster needs.

The catch is that the volume claim template inside a StatefulSet cannot be changed after creation. If you edit the template to request a larger size, the update is refused. The template only matters when new claims are created, and existing claims are not touched by it. This surprises many teams the first time they try to grow a database.

flowchart TD
    A["Need more space for a StatefulSet"] --> B["Raise the requested size on each existing claim one by one"]
    B --> C["Wait until every claim has finished expanding"]
    C --> D["Delete the StatefulSet object but keep its Pods and claims"]
    D --> E["Recreate the StatefulSet with the larger size in its template"]
    E --> F["Controller adopts the existing Pods and claims"]
    F --> G["Future replicas get the new size"]
        

Even a valid request can be blocked by rules set by administrators or by the storage provider.

An expansion request passes through several layers of control, and any of them may say no. Some belong to Kubernetes and some to the storage system.

What can go wrong, how to recognise it, and how to get back on track.

Most expansions succeed without drama. When they do not, the cause usually falls into a short list. Recognising the pattern quickly saves a lot of time.

When a volume is far too big, the only route is to build a smaller one and move the data.

Sometimes a volume is simply oversized. Maybe a one-off import filled it, then the data was deleted, and now it is mostly empty and expensive. Since shrinking is not supported, the way to reclaim the space and money is migration: create a new, smaller claim, copy the data across and switch the application over.

flowchart TD
    A["Volume is far larger than needed"] --> B["Take a backup or snapshot"]
    B --> C["Create a new smaller claim"]
    C --> D["Stop writes to the application"]
    D --> E["Copy data to the new claim"]
    E --> F["Verify the copy"]
    F --> G["Point the application at the new claim"]
    G --> H["Keep the old volume briefly, then delete it"]
        

Ways to move the data

The best method depends on the application. For databases, the safest approach is usually to use the database’s own tools, for example by adding a new replica with a smaller volume and removing the old one after replication catches up. For file data, a one-time copy job can transfer files while the application is paused. For some storage systems, restoring from a snapshot into a new claim is the quickest route, provided the driver allows the new claim to be sized as needed.

When the cluster holds a size that your configuration repository does not know about.

Many teams manage their clusters from configuration stored in a repository, applied by tools such as Helm or by GitOps controllers that continuously compare the repository with the cluster. Volume expansion interacts with this in an awkward way, because the size on the claim in the cluster can become different from the size written in the repository.

Suppose an engineer expands a claim during an incident, directly in the cluster. The repository still says the old, smaller size. The next time the tool applies the configuration, it tries to set the old size on the claim. Since shrinking is not allowed, the update is rejected. Depending on the tool, this shows up as a failed deployment, a permanently out-of-sync application or a noisy alert. The cluster is fine, but the process is broken.

Neighbouring storage features that often come up in the same conversations.

Volume expansion is only one of several ways in which an existing volume can change or be protected. Understanding its neighbours prevents confusion, and helps you pick the right tool for the job.

The best expansion is the one done calmly, days before the disk fills.

The kubelet reports usage for every mounted volume, so you can see how full each one is without logging in to any application. These numbers flow into the monitoring system as metrics, and with them you can build alerts that warn long before a disk fills.

Predictive alerts beat fixed thresholds

A fixed threshold treats a slowly growing volume and a rapidly filling one the same way. A volume at eighty percent that grows by one percent a month needs no hurry, while a volume at seventy percent that fills by ten percent an hour is in danger. Alerts based on the growth trend, which estimate the time until full, tell you what you really want to know: how long you have.

Letting a controller grow volumes before a human has to notice.

Because expansion is online and quick for many drivers, it is tempting to automate it. Community tools exist that watch the usage metrics and raise the requested size of a claim when it passes a threshold, by a set step, up to a safe maximum. This turns many night-time pages into silent, uneventful growth.

flowchart LR
    A["Kubelet reports volume usage"] --> B["Monitoring stores the metrics"]
    B --> C["Auto-expansion controller checks fill level"]
    C -->|Below threshold| D["Do nothing"]
    C -->|Above threshold and below the ceiling| E["Raise the requested size by one step"]
    E --> F["Normal two-phase expansion runs"]
    F --> A
    C -->|At the ceiling| G["Alert a human instead"]
        

Guardrails for automation

Good automation has limits. Set a maximum size per volume so a bug cannot grow a disk without end. Choose a step that is large enough to respect provider cool-downs but small enough to avoid waste. Alert people whenever an automatic expansion happens, because rapid growth is itself a signal that something is writing more than expected. And make sure the claim’s configuration in the repository is set up to tolerate growth.

Growing a disk is a small action with real financial and operational consequences.

Because expansion is as easy as editing one field, it deserves the same care as any other change that affects money and data. Several controls keep it safe.

Habits and steps that turn expansion into a calm, repeatable task.

A runbook for a planned expansion

Five habits that regularly turn a simple resize into a long night.

A balanced view of what expansion gives you and where it stops.

How it compares with the alternatives

The sensible approach in most teams combines several of these. Start with a reasonable size, enable expansion, alert on trends, grow in measured steps, and review volumes periodically so that oversized ones can be migrated and old data can be archived. Expansion is a tool for handling uncertainty, and not a replacement for knowing how fast your data grows.

How teams use volume expansion in everyday operations.

Short answers to the questions beginners ask most often.

No. Reducing the requested size of a bound claim is not supported. To get a smaller volume, create a new claim of the right size, copy the data across and switch the application to it.

Most often the storage class does not allow volume expansion. An admission check refuses size increases on such classes. Enable the setting on the class, or create a new class that allows it.

Not always. Many drivers support online expansion, so the filesystem grows while the Pod runs. Some drivers complete the filesystem step only when a Pod mounts the volume, which then requires a restart.

The first phase, growing the disk, is done, but the second phase, growing the filesystem, has not finished. Check the claim’s conditions and capacity, and make sure a Pod is mounting the volume if the driver needs one.

The claim template cannot be edited, so expand each existing claim directly, then delete the StatefulSet while leaving its Pods and claims in place, and recreate it with the larger size in the template.

It is designed to be safe and is routine, but it changes live storage. For important data, take a snapshot or backup first, and watch the process until it completes.

The repository probably still holds the old, smaller size, and the tool tries to apply it. Kubernetes refuses to shrink, so the apply fails. Update the repository to match the larger size.

Plain NFS does not enforce the requested size, so changing it has no real effect. Local volumes cannot be grown by Kubernetes itself, although some drivers built on logical volume managers support it.

Yes. Community controllers watch usage metrics and raise the requested size when a threshold is crossed. Use a maximum size, quotas and notifications so that a faulty application cannot grow disks without limit.

If the backend cannot provide it, the claim stays in an error state with retries. Recent Kubernetes versions can recover from failed expansions by letting you lower the request, as long as it stays above the current capacity. Check support in your version and driver.

Volume expansion lets you give a running application more disk space by changing one number on a claim. Behind that simple edit, Kubernetes and the storage driver work in two phases: first the backing disk is enlarged, then the filesystem on top of it is grown on the node, often while the application keeps running. It requires a storage class that allows expansion, a driver that supports it and a storage backend with room to grow, and it can be limited by quotas and provider rules. It only goes one way, so shrinking means migrating to a new volume. Stateful workloads need a careful routine because their claim templates cannot be edited, and configuration repositories must be kept in step with live sizes. With good monitoring, sensible steps and guarded automation, expansion turns a classic emergency into a routine, quiet operation.