Chapter 28. Using Persistent Volumes
28.1. Overview
A PersistentVolume
object is a storage resource in an OpenShift Container Platform cluster. Storage is provisioned by your cluster administrator by creating PersistentVolume
objects from sources such as GCE Persistent Disk, AWS Elastic Block Store (EBS), and NFS mounts.
The Installation and Configuration Guide provides instructions for cluster administrators on provisioning an OpenShift Container Platform cluster with persistent storage using NFS, GlusterFS, Ceph RBD, OpenStack Cinder, AWS EBS, GCE Persistent Disk, iSCSI, and Fibre Channel.
Storage can be made available to you by laying claims to the resource. You can make a request for storage resources using a PersistentVolumeClaim
object; the claim is paired with a volume that generally matches your request.
28.2. Requesting Storage
You can request storage by creating PersistentVolumeClaim
objects in your projects:
Persistent Volume Claim Object Definition
apiVersion: "v1" kind: "PersistentVolumeClaim" metadata: name: "claim1" spec: accessModes: - "ReadWriteOnce" resources: requests: storage: "1Gi" volumeName: "pv0001"
28.3. Volume and Claim Binding
A PersistentVolume
is a specific resource. A PersistentVolumeClaim
is a request for a resource with specific attributes, such as storage size. In between the two is a process that matches a claim to an available volume and binds them together. This allows the claim to be used as a volume in a pod. OpenShift Container Platform finds the volume backing the claim and mounts it into the pod.
You can tell whether a claim or volume is bound by querying using the CLI:
$ oc get pvc NAME LABELS STATUS VOLUME claim1 map[] Bound pv0001 $ oc get pv NAME LABELS CAPACITY ACCESSMODES STATUS CLAIM pv0001 map[] 5368709120 RWO Bound yournamespace / claim1
28.4. Claims as Volumes in Pods
A PersistentVolumeClaim
is used by a pod as a volume. OpenShift Container Platform finds the claim with the given name in the same namespace as the pod, then uses the claim to find the corresponding volume to mount.
Pod Definition with a Claim
apiVersion: "v1" kind: "Pod" metadata: name: "mypod" labels: name: "frontendhttp" spec: containers: - name: "myfrontend" image: openshift/hello-openshift ports: - containerPort: 80 name: "http-server" volumeMounts: - mountPath: "/var/www/html" name: "pvol" volumes: - name: "pvol" persistentVolumeClaim: claimName: "claim1"
28.5. Volume and Claim Pre-binding
If you know exactly what PersistentVolume
you want your PersistentVolumeClaim
to bind to, you can specify the PV in your PVC using the volumeName
field. This method skips the normal matching and binding process. The PVC will only be able to bind to a PV that has the same name specified in volumeName
. If such a PV with that name exists and is Available
, the PV and PVC will be bound regardless of whether the PV satisfies the PVC’s label selector, access modes, and resource requests.
Example 28.1. Persistent Volume Claim Object Definition with volumeName
apiVersion: "v1" kind: "PersistentVolumeClaim" metadata: name: "claim1" spec: accessModes: - "ReadWriteOnce" resources: requests: storage: "1Gi" volumeName: "pv0001"
The ability to set claimRefs
is a temporary workaround for the described use cases. A long-term solution for limiting who can claim a volume is in development.
The cluster administrator should first consider configuring selector-label volume binding before resorting to setting claimRefs
on behalf of users.
You may also want your cluster administrator to "reserve" the volume for only your claim so that nobody else’s claim can bind to it before yours does. In this case, the administrator can specify the PVC in the PV using the claimRef
field. The PV will only be able to bind to a PVC that has the same name and namespace specified in claimRef
. The PVC’s access modes and resource requests must still be satisfied in order for the PV and PVC to be bound, though the label selector is ignored.
Persistent Volume Object Definition with claimRef
apiVersion: v1 kind: PersistentVolume metadata: name: pv0001 spec: capacity: storage: 1Gi accessModes: - ReadWriteOnce nfs: path: /tmp server: 172.17.0.2 persistentVolumeReclaimPolicy: Recycle claimRef: name: claim1 namespace: default
Specifying a volumeName
in your PVC does not prevent a different PVC from binding to the specified PV before yours does. Your claim will remain Pending
until the PV is Available
.
Specifying a claimRef
in a PV does not prevent the specified PVC from being bound to a different PV. The PVC is free to choose another PV to bind to according to the normal binding process. Therefore, to avoid these scenarios and ensure your claim gets bound to the volume you want, you must ensure that both volumeName
and claimRef
are specified.
You can tell that your setting of volumeName
and/or claimRef
influenced the matching and binding process by inspecting a Bound
PV and PVC pair for the pv.kubernetes.io/bound-by-controller
annotation. The PVs and PVCs where you set the volumeName
and/or claimRef
yourself will have no such annotation, but ordinary PVs and PVCs will have it set to "yes"
.
When a PV has its claimRef
set to some PVC name and namespace, and is reclaimed according to a Retain
or Recycle
reclaim policy, its claimRef
will remain set to the same PVC name and namespace even if the PVC or the whole namespace no longer exists.