Using Persistent Volumes
Overview
A PersistentVolume
object is a storage resource in an OKD 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 Configuring Clusters guide provides instructions for cluster administrators on provisioning an OKD 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.
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"
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. OKD 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
Claims as Volumes in Pods
A PersistentVolumeClaim
is used by a pod as a volume. OKD 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"
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 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 |
The cluster administrator should first consider configuring selector-label volume binding before resorting to setting |
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: Retain
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
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.