From 318d17b85fbe851626d14e7267e7f1c14b042856 Mon Sep 17 00:00:00 2001 From: Yecheng Fu Date: Tue, 4 Aug 2020 14:19:28 +0800 Subject: [PATCH] add pre-binding section --- .../concepts/storage/persistent-volumes.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/content/en/docs/concepts/storage/persistent-volumes.md b/content/en/docs/concepts/storage/persistent-volumes.md index 8c2ad3ddb1..9fb9fdae45 100644 --- a/content/en/docs/concepts/storage/persistent-volumes.md +++ b/content/en/docs/concepts/storage/persistent-volumes.md @@ -174,6 +174,45 @@ spec: However, the particular path specified in the custom recycler Pod template in the `volumes` part is replaced with the particular path of the volume that is being recycled. +### Reserving a PersistentVolume + +The control plane can [bind PersistentVolumeClaims to matching PersistentVolumes](#binding) in the +cluster. However, if you want a PVC to bind to a specific PV, you need to pre-bind them. + +By specifying a PersistentVolume in a PersistentVolumeClaim, you declare a binding between that specific PV and PVC. +If the PersistentVolume exists and has not reserved PersistentVolumeClaims through its `claimRef` field, then the PersistentVolume and PersistentVolumeClaim will be bound. + +The binding happens regardless of some volume matching criteria, including node affinity. +The control plane still checks that [storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/), access modes, and requested storage size are valid. + +``` +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: foo-pvc + namespace: foo +spec: + volumeName: foo-pv + ... +``` + +This method does not guarantee any binding privileges to the PersistentVolume. If other PersistentVolumeClaims could use the PV that you specify, you first need to reserve that storage volume. Specify the relevant PersistentVolumeClaim in the `claimRef` field of the PV so that other PVCs can not bind to it. + +``` +apiVersion: v1 +kind: PersistentVolume +metadata: + name: foo-pv +spec: + claimRef: + name: foo-pvc + namespace: foo + ... +``` + +This is useful if you want to consume PersistentVolumes that have their `claimPolicy` set +to `Retain`, including cases where you are reusing an existing PV. + ### Expanding Persistent Volumes Claims {{< feature-state for_k8s_version="v1.11" state="beta" >}}