Change the Access Mode of a PersistentVolume to ReadWriteOncePod

This page shows how to change the access mode on an existing PersistentVolume to use ReadWriteOncePod.

Before you begin

You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:

Your Kubernetes server must be at or later than version v1.22. To check the version, enter kubectl version.

Note:

The ReadWriteOncePod access mode graduated to stable in the Kubernetes v1.29 release. If you are running a version of Kubernetes older than v1.29, you might need to enable a feature gate. Check the documentation for your version of Kubernetes.

Note:

The ReadWriteOncePod access mode is only supported for CSI volumes. To use this volume access mode you will need to update the following CSI sidecars to these versions or greater:

Why should I use ReadWriteOncePod?

Prior to Kubernetes v1.22, the ReadWriteOnce access mode was commonly used to restrict PersistentVolume access for workloads that required single-writer access to storage. However, this access mode had a limitation: it restricted volume access to a single node, allowing multiple pods on the same node to read from and write to the same volume simultaneously. This could pose a risk for applications that demand strict single-writer access for data safety.

If ensuring single-writer access is critical for your workloads, consider migrating your volumes to ReadWriteOncePod.

Migrating existing PersistentVolumes

If you have existing PersistentVolumes, they can be migrated to use ReadWriteOncePod. Only migrations from ReadWriteOnce to ReadWriteOncePod are supported.

In this example, there is already a ReadWriteOnce “cat-pictures-pvc” PersistentVolumeClaim that is bound to a “cat-pictures-pv” PersistentVolume, and a “cat-pictures-writer” Deployment that uses this PersistentVolumeClaim.

Note:

If your storage plugin supports Dynamic provisioning, the “cat-picutres-pv” will be created for you, but its name may differ. To get your PersistentVolume’s name run:

  1. kubectl get pvc cat-pictures-pvc -o jsonpath='{.spec.volumeName}'

And you can view the PVC before you make changes. Either view the manifest locally, or run kubectl get pvc <name-of-pvc> -o yaml. The output is similar to:

  1. # cat-pictures-pvc.yaml
  2. kind: PersistentVolumeClaim
  3. apiVersion: v1
  4. metadata:
  5.   name: cat-pictures-pvc
  6. spec:
  7.   accessModes:
  8.   - ReadWriteOnce
  9.   resources:
  10.     requests:
  11.       storage: 1Gi

Here’s an example Deployment that relies on that PersistentVolumeClaim:

  1. # cat-pictures-writer-deployment.yaml
  2. apiVersion: apps/v1
  3. kind: Deployment
  4. metadata:
  5.   name: cat-pictures-writer
  6. spec:
  7.   replicas: 3
  8.   selector:
  9.     matchLabels:
  10.       app: cat-pictures-writer
  11.   template:
  12.     metadata:
  13.       labels:
  14.         app: cat-pictures-writer
  15.     spec:
  16.       containers:
  17.       - name: nginx
  18.         image: nginx:1.14.2
  19.         ports:
  20.         - containerPort: 80
  21.         volumeMounts:
  22.         - name: cat-pictures
  23.           mountPath: /mnt
  24.       volumes:
  25.       - name: cat-pictures
  26.         persistentVolumeClaim:
  27.           claimName: cat-pictures-pvc
  28.           readOnly: false

As a first step, you need to edit your PersistentVolume’s spec.persistentVolumeReclaimPolicy and set it to Retain. This ensures your PersistentVolume will not be deleted when you delete the corresponding PersistentVolumeClaim:

  1. kubectl patch pv cat-pictures-pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

Next you need to stop any workloads that are using the PersistentVolumeClaim bound to the PersistentVolume you want to migrate, and then delete the PersistentVolumeClaim. Avoid making any other changes to the PersistentVolumeClaim, such as volume resizes, until after the migration is complete.

Once that is done, you need to clear your PersistentVolume’s spec.claimRef.uid to ensure PersistentVolumeClaims can bind to it upon recreation:

  1. kubectl scale --replicas=0 deployment cat-pictures-writer
  2. kubectl delete pvc cat-pictures-pvc
  3. kubectl patch pv cat-pictures-pv -p '{"spec":{"claimRef":{"uid":""}}}'

After that, replace the PersistentVolume’s list of valid access modes to be (only) ReadWriteOncePod:

  1. kubectl patch pv cat-pictures-pv -p '{"spec":{"accessModes":["ReadWriteOncePod"]}}'

Note:

The ReadWriteOncePod access mode cannot be combined with other access modes. Make sure ReadWriteOncePod is the only access mode on the PersistentVolume when updating, otherwise the request will fail.

Next you need to modify your PersistentVolumeClaim to set ReadWriteOncePod as the only access mode. You should also set the PersistentVolumeClaim’s spec.volumeName to the name of your PersistentVolume to ensure it binds to this specific PersistentVolume.

Once this is done, you can recreate your PersistentVolumeClaim and start up your workloads:

  1. # IMPORTANT: Make sure to edit your PVC in cat-pictures-pvc.yaml before applying. You need to:
  2. # - Set ReadWriteOncePod as the only access mode
  3. # - Set spec.volumeName to "cat-pictures-pv"
  5. kubectl apply -f cat-pictures-pvc.yaml
  6. kubectl apply -f cat-pictures-writer-deployment.yaml

Lastly you may edit your PersistentVolume’s spec.persistentVolumeReclaimPolicy and set to it back to Delete if you previously changed it.

  1. kubectl patch pv cat-pictures-pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}'

What’s next