Persistent Volume Access Modes

Kubernetes Persistent Volume access modes define how a volume can be mounted by nodes in a cluster, governing concurrency and read/write behavior.

Table of Contents#

1. Overview
2. Access Mode Definitions
3. CSI Driver Backend Support
4. StorageClass Examples
5. StatefulSet vs Deployment Considerations
6. Performance Implications
7. Choosing the Right Access Mode
8. Troubleshooting
9. See Also
10. Sources

1. Overview#

Persistent Volumes (PVs) in Kubernetes abstract the underlying storage implementation and expose it to pods via Persistent Volume Claims (PVCs). Each PV declares which access modes it supports, and each PVC requests a specific access mode. The access mode determines whether the volume can be mounted by a single node or multiple nodes, and whether writes are permitted.

Access modes are enforced at the node level, not the pod level. A volume with ReadWriteOnce can be mounted by multiple pods, provided they all run on the same node.

2. Access Mode Definitions#

ReadWriteOnce (RWO)#

• Abbreviation: ReadWriteOnce
• Behavior: The volume can be mounted as read-write by a single node
• Multiple pods: Yes, if all pods are on the same node
• Use cases: Single-instance databases (PostgreSQL, MySQL), application state directories, CI build caches

ReadOnlyMany (ROX)#

• Abbreviation: ReadOnlyMany
• Behavior: The volume can be mounted as read-only by many nodes simultaneously
• Multiple pods: Yes, across multiple nodes, all read-only
• Use cases: Shared configuration data, static web content, pre-built machine learning models, shared certificate stores

ReadWriteMany (RWX)#

• Abbreviation: ReadWriteMany
• Behavior: The volume can be mounted as read-write by many nodes simultaneously
• Multiple pods: Yes, across multiple nodes, all read-write
• Use cases: Shared upload directories, CMS media storage, shared build artifacts, collaborative application data

ReadWriteOncePod (RWOP)#

• Abbreviation: ReadWriteOncePod (Kubernetes 1.27+ GA)
• Behavior: The volume can be mounted as read-write by a single pod on a single node
• Multiple pods: No, strictly one pod cluster-wide
• Use cases: Databases requiring exclusive access guarantees, leader-election storage, write-ahead logs

3. CSI Driver Backend Support#

Not all storage backends support all access modes. The table below maps common CSI drivers to their supported modes:

4. StorageClass Examples#

Longhorn (RWO, Default)#

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"
  dataLocality: "best-effort"
reclaimPolicy: Delete
volumeBindingMode: Immediate
allowVolumeExpansion: true

Longhorn RWX#

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-rwx
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "3"
  nfsOptions: "vers=4.1,hard,timeo=600"
reclaimPolicy: Delete
volumeBindingMode: Immediate
allowVolumeExpansion: true

NFS#

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs
provisioner: nfs.csi.k8s.io
parameters:
  server: <nfs-server-ip>
  share: /srv/nfs/k8s
reclaimPolicy: Delete
volumeBindingMode: Immediate
mountOptions:
  - nfsvers=4.1
  - hard
  - noatime

Ceph RBD#

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ceph-rbd
provisioner: rbd.csi.ceph.com
parameters:
  clusterID: <ceph-cluster-id>
  pool: kubernetes
  imageFeatures: layering
  csi.storage.k8s.io/provisioner-secret-name: csi-rbd-secret
  csi.storage.k8s.io/provisioner-secret-namespace: ceph-system
  csi.storage.k8s.io/node-stage-secret-name: csi-rbd-secret
  csi.storage.k8s.io/node-stage-secret-namespace: ceph-system
reclaimPolicy: Delete
allowVolumeExpansion: true

PVC Requesting a Specific Access Mode#

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 10Gi

5. StatefulSet vs Deployment Considerations#

When to Use Each#

• StatefulSet with RWO: Databases (PostgreSQL, MySQL, MongoDB), message brokers (Kafka, RabbitMQ), any workload needing per-instance persistent state
• Deployment with RWX: Shared media uploads, CMS content, log aggregation directories, shared build caches
• Deployment with RWO: Single-replica applications with persistent state (simple, no scaling)
• Deployment with ROX: Configuration or static content distributed to many read-only replicas

6. Performance Implications#

Key considerations:

• RWX via NFS adds a protocol translation layer, increasing latency compared to direct block access
• Longhorn RWX creates an NFS share manager pod per volume, consuming additional CPU and memory
• For read-heavy workloads, ROX with client-side caching can outperform RWX
• RWOP guarantees exclusive access, enabling filesystem optimizations (no lock contention)

7. Choosing the Right Access Mode#

Decision process:

1. Does the workload need write access?
   • No: Use ROX
   • Yes: Continue
2. Do multiple pods on different nodes need write access?
   • No: Use RWO (or RWOP for strict single-pod guarantee)
   • Yes: Use RWX
3. Is the storage backend compatible?
   • Check the CSI driver support table above
   • If RWX is needed but the backend only supports RWO, consider NFS on top of block storage or a different backend
4. Are you using StatefulSet or Deployment?
   • StatefulSet: RWO is usually sufficient since each pod gets its own PVC
   • Deployment with replicas > 1: RWX is required if pods land on different nodes

Troubleshooting#

See Also#

• A GitOps Kubernetes cluster, layer by layer
• Longhorn
• NFS
• Ceph

Sources#

• Kubernetes - Persistent Volumes
• Kubernetes - Access Modes
• Kubernetes - Storage Classes
• Longhorn - RWX Volume Documentation
• Ceph CSI - Configuration