Document PV & PVC pre-binding scenarios

dev_guide/persistent_volumes.adoc

@@ -12,9 +12,10 @@
 toc::[]
 
 == Overview
-A `*PersistentVolume*` object is a storage resource in an {product-title} cluster.
+
+A `PersistentVolume` object is a storage resource in an {product-title} cluster.
 Storage is provisioned by your cluster administrator by creating
-`*PersistentVolume*` objects from sources such as GCE Persistent Disk, AWS
+`PersistentVolume` objects from sources such as GCE Persistent Disk, AWS
 Elastic Block Store (EBS), and NFS mounts.
 
 ifdef::openshift-enterprise,openshift-origin[]
@@ -40,11 +41,13 @@ Channel].
 endif::[]
 
 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;
+make a request for storage resources using a `PersistentVolumeClaim` object;
 the claim is paired with a volume that generally matches your request.
 
+[[persistent-volumes-requesting-storage]]
 == Requesting Storage
-You can request storage by creating `*PersistentVolumeClaim*` objects in your
+
+You can request storage by creating `PersistentVolumeClaim` objects in your
 projects:
 
 .Persistent Volume Claim Object Definition
@@ -66,8 +69,10 @@ spec:
 ----
 ====
 
+[[persistent-volumes-volume-and-claim-building]]
 == Volume and Claim Binding
-A `*PersistentVolume*` is a specific resource. A `*PersistentVolumeClaim*` is a
+
+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.
@@ -87,9 +92,10 @@ pv0001              map[]               5368709120          RWO
 ----
 ====
 
+[[persistent-volumes-claims-as-volumes-in-pods]]
 == Claims as Volumes in Pods
 
-A `*PersistentVolumeClaim*` is used by a pod as a volume. {product-title} finds the
+A `PersistentVolumeClaim` is used by a pod as a volume. {product-title} 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.
 
@@ -124,3 +130,100 @@ spec:
         claimName: "claim1"
 ----
 ====
+
+[[persistent-volumes-volumes-and-claim-prebinding]]
+== 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.
+
+.Persistent Volume Claim Object Definition with volumeName
+====
+
+[source,yaml]
+----
+apiVersion: "v1"
+kind: "PersistentVolumeClaim"
+metadata:
+  name: "claim1"
+spec:
+  accessModes:
+    - "ReadWriteOnce"
+  resources:
+    requests:
+      storage: "5Gi"
+  volumeName: "pv0001"
+----
+====
+
+[IMPORTANT]
+====
+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.
+====
+
+[NOTE]
+====
+The cluster administrator should first consider configuring
+xref:../install_config/persistent_storage/selector_label_binding.adoc#selector-label-volume-binding[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
+====
+
+[source,yaml]
+----
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: pv0001
+spec:
+  capacity:
+    storage: 5Gi
+  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` recycling policy, its `claimRef`
+will remain set to the same PVC name and namespace even if the PVC or the whole
+namespace no longer exists.