To understand access modes we first need a handful of simple words: volume, node, pod, claim and mode.

So what exactly is an access mode?

An access mode is a statement about a storage volume. It answers two simple questions. First, who may attach to the volume at the same time: one node, many nodes, or a single pod. Second, what they may do: read and write, or read only. Every persistent volume lists the modes its storage can support, and every claim lists the mode it needs. Kubernetes then matches claims to volumes so that a pod only receives storage that behaves the way it expects.

Think of access modes as the label on the box, not the lock on the door. They describe what the storage is designed for, and Kubernetes uses that description to make sensible decisions. This difference between a label and a lock will matter a great deal later in this guide.

The four modes at a glance

Kubernetes defines four access modes. Three are old and well known. The fourth is newer and more strict.

Storage is not all alike. Some kinds can be shared by many machines, and some can be held by only one. A cluster must know the difference before it places your pod.

Real storage has real limits

Behind every persistent volume sits a real technology: a network disk in a cloud, a shared file server, a distributed file system or a disk inside a machine. Each behaves differently. A cloud block disk is like a hard drive plugged into a single computer, and it cannot safely be plugged into two computers at once. A shared file server, on the other hand, is built to serve many computers together. Kubernetes has to respect these facts, or data gets corrupted.

What people did before

flowchart LR
  subgraph W["Without access modes"]
    A1["App asks for storage"] --> B1["Any disk is handed over"]
    B1 --> C1["Two nodes write to a single-node disk"]
    C1 --> D1["Data damage or stuck pods"]
  end
  subgraph V["With access modes"]
    A2["App asks for storage and states how it will be used"] --> B2["Kubernetes matches a compatible volume"]
    B2 --> C2["Volume behaves as promised"]
  end
    

Reading Figure 1

The left half shows what could go wrong. An application asks for storage and simply receives some disk. If that disk is built for a single machine and two machines write to it, the data is damaged or the pod gets stuck. The right half shows the calmer world. The application states how it will use the storage. Kubernetes looks for a volume that promises compatible behaviour. The application receives what it expects, and the risky mismatch is caught before any pod starts.

Access modes sit inside a small family of storage objects. Meet the family first, and the modes will make sense.

Two ideas that people mix up

Two words sound similar and mean different things: attach and mount. To attach a volume means to connect the storage to a node, like plugging a disk into a computer. To mount means to make the connected storage appear as a folder that a container can see. The access mode’s “once” and “many” refer to the node level: how many nodes may have the volume attached. That is why RWO allows several pods, so long as they all sit on the same node.

The label and the lock

Here is the most important idea in the whole guide. An access mode is a description of what the storage can do, used by Kubernetes for matching and scheduling. It is not a full security lock. Kubernetes does not, on its own, stop a volume from being used in a way that the storage cannot actually handle. The real safety comes from the storage system’s own behaviour, together with careful use of the mode. For example, marking a claim as read-only in a pod is enforced at mount time, but nothing in the label prevents an administrator from mounting the same underlying disk somewhere else outside Kubernetes.

Who chooses what

Several pieces cooperate between a claim and a real disk. It helps to see who talks to whom.

flowchart TB
  U["User writes a claim with an access mode"] --> PVC["Persistent volume claim"]
  PVC -->|"Matched or created"| PV["Persistent volume with supported modes"]
  SC["Storage class"] -->|"Recipe for new volumes"| PV
  PV --> CSI["Storage driver"]
  CSI --> ST["Real storage system"]
  POD["Pod names the claim"] --> PVC
  SCH["Scheduler"] -->|"Chooses a node that can use the volume"| POD
  KL["Kubelet on the node"] -->|"Asks driver to attach and mount"| CSI
    

Reading Figure 2 piece by piece

Start at the top left. A user writes a claim that asks for some space and names an access mode. Kubernetes tries to find a persistent volume that satisfies it. If none exists and the claim names a storage class, the class acts as a recipe to create a fresh volume on demand. The volume is backed by a real storage system through a driver.

On the other side, a pod names the claim in its definition. The scheduler must choose a node for the pod, and it takes the volume’s constraints into account, such as whether the volume is already attached elsewhere. Once a node is chosen, the kubelet on that node asks the driver to attach the volume to the node and mount it into the container.

The parts, one by one

Who really enforces the mode?

The attach and detach controller, together with the driver, is the piece that acts on the mode in practice. If a volume is marked for single-node use and it is already attached to one node, a request to attach it to a second node is refused or delayed. The pod that needed it stays in a waiting state and reports a message about the volume. This behaviour is the source of many puzzling pod problems, and we return to it in detail in later chapters.

Now let us open the box. We will see how Kubernetes matches a claim to a volume, and then how it uses the mode when attaching storage to a node.

Matching a claim to a volume

When a claim appears, a controller looks for a volume that satisfies several conditions at once. The volume must be large enough. It must belong to the same storage class as the claim, or both must have none. Its list of supported modes must include every mode the claim asks for. Any label selector on the claim must match the volume. And the volume must not already belong to another claim. From the volumes that pass, the controller usually picks the smallest one that fits, to avoid waste.

flowchart TD
  S["New claim arrives"] --> A{"Existing volume large enough?"}
  A -->|"No"| N["Try to create a new volume through the storage class"]
  A -->|"Yes"| B{"Same storage class?"}
  B -->|"No"| N
  B -->|"Yes"| C{"Volume supports the requested access mode?"}
  C -->|"No"| N
  C -->|"Yes"| D{"Volume still free and selector matches?"}
  D -->|"No"| N
  D -->|"Yes"| OK["Bind claim to the smallest matching volume"]
  N --> E{"Creation possible?"}
  E -->|"Yes"| OK
  E -->|"No"| P["Claim stays pending"]
    

Reading Figure 3

A new claim first goes through four tests against existing volumes: size, storage class, mode and freedom. Failing any test sends the claim to the “create new” path. If a storage class and driver exist, a new volume is created with the requested mode and the claim is bound to it. If creation is impossible, for example because the driver cannot provide the requested mode, the claim stays pending, with an event that explains the reason.

Two details are worth remembering. First, the mode test is a subset test: a volume that supports several modes can satisfy a claim that asks for just one of them. Second, once a claim and a volume are bound, the pair is exclusive. The binding is one to one, even if the volume’s mode says many nodes may use it.

Many modes on the volume, one in use

A persistent volume may list several supported modes, for example single-node write and many-node read-only. But only one mode is in effect at any moment. A volume cannot be mounted with two different modes at the same time. If a volume supports both, the first way it is used decides the mode until it is released.

From claim to attached disk

Static and dynamic provisioning

Volumes reach a claim in two ways. In static provisioning, an administrator creates volumes by hand ahead of time, listing each one’s size and supported modes, and claims bind to whichever fits. In dynamic provisioning, nobody pre-creates anything. A claim names a storage class, and the driver creates a fresh volume on demand with exactly the requested size and mode. Dynamic provisioning is far more common today, because it removes waiting and guesswork. With static volumes the administrator must decide the modes in advance and get them right. With dynamic volumes, the class and driver decide which modes are possible, and a request outside that set simply fails to provision.

One consequence is that with dynamic provisioning, the practical question is not “which volume matches” but “which class can create the mode I need”. Choosing the class is therefore choosing the mode’s feasibility.

Location matters for many storage kinds

Many cloud disks live in one data-centre zone and can only be attached to nodes in that same zone. To avoid creating a disk in a zone where the pod cannot run, storage classes often use a setting that delays creation until a pod is scheduled, called wait for first consumer. The disk is then created in the zone where the pod actually landed. This detail interacts with access modes because a single-node disk pins the pod to the disk’s zone from then on.

Let us follow one volume from the moment a claim is written to the moment the pod is gone.

sequenceDiagram
  participant U as User
  participant C as Binding controller
  participant D as Storage driver
  participant S as Scheduler
  participant A as Attach controller
  participant K as Kubelet
  U->>C: Create claim with an access mode
  C->>D: Create a volume that supports the mode
  D-->>C: Volume ready
  C-->>U: Claim bound
  U->>S: Create pod that uses the claim
  S->>S: Choose a node that can use the volume
  S->>A: Pod placed on node
  A->>D: Attach the volume to the node
  D-->>A: Attached
  K->>D: Mount into the pod
  K-->>U: Pod running with storage
  U->>K: Delete pod later
  K->>D: Unmount
  A->>D: Detach from the node
    

Reading Figure 4

The story begins with the user creating a claim. The binding controller asks the driver to create a suitable volume, and the claim becomes bound. Later a pod that uses the claim is created. The scheduler picks a node, the attach controller connects the volume to that node, and the kubelet mounts it into the pod. When the pod is deleted, the kubelet unmounts the volume and the attach controller detaches it. Only after detaching can a single-node volume be attached somewhere else.

Six stages of a volume’s life

What if something goes wrong?

If the pod is deleted and the node is fine, detach happens quickly. But if the node itself crashes, the cluster may not know for certain that the disk is no longer in use there. To avoid two nodes writing at once, Kubernetes and the driver are cautious: they wait until the old node is confirmed gone or the attachment is safely released. That safety delay is why a replacement pod on a new node can take several minutes to start after a node failure. It is a price paid for protecting data.

Each mode has a personality, common uses and common traps. Let us meet them one at a time.

ReadWriteOnce: one node writes

ReadWriteOnce is the most common mode, and the most misunderstood. It says that the volume can be mounted read-write by one node at a time. The word “once” refers to the node, not to the pod. If three pods land on the same node, all three may use the volume together. If they land on different nodes, only the first node succeeds, and the others must wait.

flowchart LR
  subgraph N1["Node 1"]
    OLD["Old pod, using the volume"]
  end
  subgraph N2["Node 2"]
    NEW["New pod, needs the same volume"]
  end
  V["Single-node volume, attached to Node 1"]
  OLD --> V
  NEW -.->|"Cannot attach while Node 1 holds it"| V
    

Reading Figure 5

The old pod sits on the first node, holding the volume. During an update, Kubernetes wants to start the new pod before removing the old one, to avoid downtime. If the scheduler places the new pod on the second node, that node needs the volume too. The volume is still attached to the first node, so the attachment is refused. The new pod waits, the old pod cannot be removed because the update expects the new pod to become ready, and the rollout appears frozen. Solutions are covered in Chapter 10.

ReadOnlyMany: many nodes read

ReadOnlyMany allows many nodes to mount the volume at once, but only for reading. It suits reference data that must be shared without risk of change: configuration bundles, machine-learning models, static website content and shared libraries. The data is usually prepared beforehand, for example by restoring a snapshot or copying files in a one-off job, and then presented read-only to all consumers.

ReadWriteMany: many nodes write

ReadWriteMany allows many nodes to mount and write at once. It is the mode most people want and the hardest to provide, because the storage itself must coordinate the writers. It is backed by network file systems and distributed file systems rather than plain block disks. Typical uses include shared upload folders for web servers, content management systems and shared working areas for batch jobs.

The storage coordinates access to files, but it cannot coordinate the meaning of the data. Two application copies writing to the same file at the same moment can still corrupt it, unless the application uses locking or writes to distinct files. Databases are usually a poor fit for shared file storage for exactly this reason.

ReadWriteOncePod: one pod writes

ReadWriteOncePod is a stricter form of single-writer access. It guarantees that only one pod in the entire cluster can use the volume at once, even if other pods sit on the same node. It was added to close the gap left by the “once per node” behaviour. It is ideal for applications that must never have two instances touching the same data. Support depends on the Kubernetes version and on the storage driver, so verify both before relying on it.

Five common misconceptions

A mode is only useful if the storage behind it can deliver it. Here is the general picture, with the reminder that drivers differ and change.

Why the same mode can behave differently

Two drivers that both say “many nodes, read-write” may behave differently under pressure. One might offer strict file locking, another might not. One might be fast for small files, another for big streams. The mode tells Kubernetes what may be attached; it says nothing about speed, locking guarantees or consistency. Always test the storage for your actual workload.

Testing a mode before you trust it

A short experiment beats a long debate. Create a test claim in the mode you need and start two small test pods that use it, forcing them onto different nodes. For a single-node mode, expect the second pod to wait, and confirm that the message names the volume and the first node. For a many-node mode, expect both pods to run, then write a file from one pod and read it from the other. Try deleting the first pod and watch how quickly the second keeps working. Repeat the test after a simulated node failure in a non-production cluster. Keep the results in your team’s notes, together with the storage class name and the driver version, so that future upgrades can be checked against the same experiment in minutes.

How to find out what your storage supports

Access modes are about safe sharing, but they are only one layer. This chapter shows what they protect, what they leave open, and what else you need.

What access modes do protect

Modes help prevent one class of accident: two machines writing to storage that cannot handle it. By refusing a second attachment to a single-node volume, the cluster protects file systems from corruption. By presenting a volume read-only, it protects reference data from accidental change by applications.

What they do not protect

Layers that complete the picture

Read-only, at two levels

There are two separate ways to make a volume read-only, and people often mix them up. One is the access mode on the claim and volume, such as read-only for many nodes, which describes how the storage may be attached. The other is a read-only setting on the pod’s own mount, which prevents that pod from writing even if the underlying volume allows writing. For a single-node volume that one pod must only read, use the pod-level setting. For shared reference data across many nodes, use the read-only mode and also mount read-only in each pod, so both layers agree.

The mode you need depends on how many copies of your application run, where they run and who writes.

flowchart TD
  A["What does my application do with the storage?"] --> B{"Does it only read shared data?"}
  B -->|"Yes"| C["ReadOnlyMany"]
  B -->|"No, it writes"| D{"Do many pods on many nodes need to write to the same volume?"}
  D -->|"Yes"| E["ReadWriteMany on shared file storage, with careful application design"]
  D -->|"No, one instance owns the data"| F{"Must the cluster guarantee only one pod ever uses it?"}
  F -->|"Yes"| G["ReadWriteOncePod"]
  F -->|"No"| H["ReadWriteOnce"]
    

Reading Figure 6

Start with the top question: does the application only read the shared data? If yes, the read-only many-node mode fits, with data prepared in advance. If it writes, ask whether many pods on many nodes must write to the same volume. If yes, choose the many-node write mode on shared file storage, and design the application to avoid conflicts. If one instance owns the data, the last question is how strict you must be. When the cluster must guarantee that no second pod ever touches it, choose the single-pod mode. Otherwise the single-node write mode is the simple, well-supported default.

Match the workload shape to the storage

Workload types and single-node volumes

The kind of workload object you use decides how gracefully it copes with single-node volumes. A deployment creates interchangeable pods and shares one claim among all of them. That is fine for one copy, and troublesome for several copies on several nodes. A stateful workload is designed for the opposite situation: each replica receives its own claim from a template, so every copy owns private storage. It also starts and stops replicas in an orderly way that respects the single-writer rule.

The mode you pick shapes both the speed and the recovery time of your application.

Speed

Block disks used with single-node modes are usually fast and predictable. They behave like local drives, with low delay and good throughput for databases. Shared file storage used with many-node modes adds network hops and coordination work, so each operation typically takes longer, and small-file workloads can suffer most. This is why heavy databases usually prefer block storage, even though many-node storage looks more flexible.

Availability and recovery

Single-node volumes tie a pod’s recovery speed to the detach process. After an ordinary pod restart on the same node, the volume is simply reused and recovery is fast. After a move to another node, the disk must detach and attach, taking seconds. After a node failure, safety delays may stretch this to minutes. Many-node storage removes the attach problem entirely, since pods on any node can mount the storage, so replacement pods start quickly, at the price of extra network cost and reliance on a shared service.

Choosing between speed and recovery in practice

Consider two teams with the same application. The first stores its data on fast single-node block storage and accepts that a node failure may cost several minutes of downtime, while its application replicates data to a standby copy for faster failover. The second stores its data on shared file storage so that any node can restart the pod at once, and accepts slower file operations. Both designs are reasonable. The first suits a busy database, where every millisecond counts and replication is well understood. The second suits a content workflow, where files are large, operations are few, and instant restarts matter more than raw speed. Notice that neither team chose a mode in isolation: each chose a whole design in which the mode, the storage and the application’s own behaviour fit together.

When you compare designs, test with realistic data volumes and failure drills. Pull the plug on a node in a test cluster, measure how long recovery really takes, and see whether the application copes with the delay. Real measurements settle arguments that opinions cannot.

Zones and location

Cloud block disks belong to one zone. A pod using such a disk can only run on nodes in that zone. If that zone has no free capacity or suffers an outage, the pod cannot move elsewhere, and the data stays unreachable until the zone recovers or you restore from a snapshot. Plan snapshots and cross-zone copies for anything important, and consider replicating data at the application level for high availability.

Every choice buys something and costs something. Here is an honest ledger of the access mode system and of the modes themselves.

Trade-offs in plain words

The first trade-off is safety against flexibility. A single-writer mode is the safest and simplest to reason about, but it limits your application to one node’s worth of writers. Many-node write access is flexible, but it moves the burden of coordination onto your application and your storage.

The second is speed against sharing. Block disks are fast and single-node. Shared file storage is shareable and slower. There is rarely a free lunch, and the best designs place fast single-writer storage under databases and shared storage only where sharing is truly needed.

The third is strictness against compatibility. The single-pod mode gives the strongest guarantee, but it depends on newer versions and driver support. The single-node mode is universally supported but leaves a gap for several pods on the same node. Teams choose based on how much risk they can accept and how modern their platform is.

The fourth is simplicity against resilience. One claim shared by a deployment is easy to write but fragile in updates and failures. A per-replica claim from a template needs more thought but survives real-world events with far less drama.

When a pod is stuck on storage, the status and events usually name the cause. Learn the common messages and you can fix most problems in minutes.

Symptoms and where to look

A calm troubleshooting routine

First, look at the claim. Is it bound? A pending claim points to matching or creation problems; read its events. Second, look at the pod’s events and status: a message about an attachment, a mount or a scheduling conflict identifies the stage that failed. Third, find out where the volume is attached now and which pod holds it. Fourth, compare the modes: the claim’s requested mode, the volume’s supported modes, and what the driver documents. Fifth, check the pod’s mount settings for read-only flags and the file ownership inside the volume. Sixth, check the storage system itself for health, capacity and zone problems.

A second worked example: the read-only surprise

A pod starts, but its application logs say it cannot write to its data folder. The claim is bound and the mount succeeded, so the storage stage is fine. The team checks the mount settings in the pod definition and finds a read-only flag left over from a template copied from a reference-data workload. Removing the flag and restarting fixes the problem. A second possible cause would have been a file system that switched itself to read-only after an error, which shows up in the node’s logs. The lesson: when writes fail on a bound and mounted volume, check the mount flag first, the file system health second and file ownership third.

What to monitor all the time

Track claims stuck in a pending state, pods stuck creating because of storage, attach and mount durations, volume capacity used against capacity requested, and driver errors. Alert on claims pending longer than a few minutes and on capacity nearing its limit. Watching attach times over weeks reveals slowly degrading storage before it causes an outage.

A pattern is a proven way of solving a repeated problem. An anti-pattern is a tempting habit that keeps causing pain.

Patterns worth adopting

Anti-patterns to avoid

This chapter gathers the advice into checklists you can keep beside your desk.

Best practices

Common mistakes

A platform guide for your teams

If you run a cluster for other teams, write a one-page storage guide and keep it up to date. It should list each storage class by name, in plain words: what kind of storage it creates, which modes it supports, how fast it is, what it costs, whether it survives a zone failure and whether snapshots are available. Next to the list, give a short decision chart like the one in Chapter 10, and a few sentences on the most common traps, such as sharing a single-node claim among many replicas. Developers who can read a page like this rarely need to ask for help, and administrators spend far less time on stuck-pod tickets.

It also helps to set defaults wisely. Make the default class the safe, common choice, usually single-node block storage created when the pod is placed. Provide shared file storage as a clearly named alternative, so choosing many-node access is a deliberate act rather than an accident. Use quotas to stop a single team from claiming huge amounts of expensive shared storage without a conversation.

Sizing and growing volumes

Access modes do not change how big a volume is, but modes and sizing interact in practice. Single-node block volumes are often resizable while in use, if the driver allows expansion, which makes it easy to start small and grow. Shared file storage may grow automatically or have generous limits, but its cost per unit is often higher. Always leave headroom, watch used capacity, and alert well before a volume fills, because a full volume causes application errors that look like unrelated bugs. Remember that shrinking is rarely supported, so start modestly and grow with evidence.

These generic stories, based on common patterns rather than any specific company, show how the modes play out.

Three worked scenarios: thinking like a designer

A short mental checklist for new storage

Before writing a claim, pause and walk through a short list. State in one sentence what the data is and who writes it. Count how many pods will write at once and on how many nodes. Decide whether the data is shared reference material that could be read-only. Decide what happens on a rolling update and on a node failure. Check which classes your cluster offers and which modes they support. Decide how you will back up and restore. Finally, decide whether the data could live somewhere simpler, such as object storage. Ten minutes on this list prevents most of the problems in this article.

Quick answers to the questions beginners ask most often.

This post was written without live web research. Please verify version-sensitive details, such as ReadWriteOncePod support and driver behaviour, against the official documentation for your Kubernetes version.

Let us close the loop, returning to the shared office from the start of this article.

Just as an office needs clear rules about the private locker, the noticeboard and the shared whiteboard, a cluster needs clear rules about its storage. Access modes are those rules. They tell Kubernetes whether a volume may be written by one node, read by many nodes, written by many nodes or claimed by a single pod, and Kubernetes uses that description to match, schedule and attach storage safely.

You met the problem of blindly shared storage, the family of volume, claim and class, and the architecture from claim to attached disk. You followed a volume’s life, studied each mode in depth, saw which storage supports which mode, and learned about security, performance, trade-offs, troubleshooting and the mistakes that trap teams most often.

Snapshots, clones and moving between modes

Because a bound claim’s mode is normally fixed, changing modes is really a migration. The typical path is to take a snapshot of the existing volume, or copy its data with a one-time job, and create a new claim with the desired mode from that snapshot or copy. The application is then switched to the new claim. Snapshots also give a clean way to produce read-only many-node data: prepare the data once on a writable volume, snapshot it, and restore the snapshot into a volume presented read-only to many pods. This pattern keeps the original safe and lets consumers scale without contention.

Rehearse any migration on a copy first, check file ownership and permissions after the move, and plan a short freeze of writes so that no changes are lost between the snapshot and the switch.

Version drift and things to verify

Kubernetes storage changes steadily. The single-pod mode arrived after the original three, and support depends on cluster and driver versions. Driver capabilities, safety delays and default classes differ across platforms and releases. Because this article was written without live web research, treat version-specific statements as a starting point. Before relying on a feature in production, read the documentation for your exact version, try it in a test cluster with pods on more than one node, and record the versions in your team’s notes so upgrades prompt a re-check.

A small glossary to keep nearby

Key takeaways