WIP: Postpone Deletion of a Persistent Volume Claim in case It Is Use…

…d by a Pod Documentation

docs/admin/admission-controllers.md

@@ -329,6 +329,11 @@ This plug-in also protects the access to `metadata.ownerReferences[x].blockOwner
 of an object, so that only users with "update" permission to the `finalizers`
 subresource of the referenced *owner* can change it.
 
+### Persistent Volume Claim Protection
+
+The `PVCProtection` plugin protects Persistent Volume Claims (PVCs) that are being actively used by a pod from being deleted by adding `kubernetes.io/pvc-protection` finalizer to newly created PVCs.
+In case a user deletes a PVC that is not actively used by a pod the PVC's finalizer is removed by PVC Protection Controller.
+
 ### PersistentVolumeLabel
 
 This plug-in automatically attaches region or zone labels to PersistentVolumes

docs/admin/authorization/rbac.md

@@ -546,6 +546,7 @@ These roles include:
 * system:controller:node-controller
 * system:controller:persistent-volume-binder
 * system:controller:pod-garbage-collector
+* system:controller:pvc-protection-controller
 * system:controller:replicaset-controller
 * system:controller:replication-controller
 * system:controller:resourcequota-controller

docs/concepts/storage/persistent-volumes.md

@@ -70,6 +70,24 @@ Pods use claims as volumes. The cluster inspects the claim to find the bound vol
 
 Once a user has a claim and that claim is bound, the bound PV belongs to the user for as long as they need it. Users schedule Pods and access their claimed PVs by including a persistentVolumeClaim in their Pod's volumes block. [See below for syntax details](#claims-as-volumes).
 
+### Persistent Volume Claim Protection
+In case the [PVC protection alpha feature](/docs/tasks/administer-cluster/pvc-protection/) is switched on, a PVC is being actively used by a pod and a user deletes the PVC the PVC is not deleted immediately, but the PVC deletion is postponed until it is not actively used by any pods.
+
+Such situation is indicated by the `Terminating` status of the PVC and the presence of the `kubernetes.io/pvc-protection` finalizer in the `Finalizers` list as shown below:
+```shell
+kubectl described pvc hostpath
+Name:          hostpath
+Namespace:     default
+StorageClass:  example-hostpath
+Status:        Terminating
+Volume:        
+Labels:        <none>
+Annotations:   volume.beta.kubernetes.io/storage-class=example-hostpath
+               volume.beta.kubernetes.io/storage-provisioner=example.com/hostpath
+Finalizers:    [kubernetes.io/pvc-protection]
+...
+```
+
 ### Reclaiming
 
 When a user is done with their volume, they can delete the PVC objects from the API which allows reclamation of the resource. The reclaim policy for a `PersistentVolume` tells the cluster what to do with the volume after it has been released of its claim. Currently, volumes can either be Retained, Recycled or Deleted.

docs/tasks/administer-cluster/pvc-protection.md

@@ -0,0 +1,36 @@
+---
+approvers:
+- msau42
+- jsafrane
+title: Persistent Volume Claim Protection
+---
+
+{% capture overview %}
+{% include feature-state-alpha.md %}
+
+As of Kubernetes 1.9, persistent volume claims (PVCs) that are actively used by a pod can be protected from pre-mature delettion.
+
+{% endcapture %}
+
+{% capture prerequisites %}
+
+- A v1.9 or higher Kubernetes must be installed.
+
+{% endcapture %}
+
+{% capture steps %}
+
+## PVC Protection Configuration
+
+As PVC Protection is an alpha feature it must be turned on:
+1. Admission controller must be started with the PVC Protection plugin.
+2. All kubelets must be started with the `PVCProtection` alpha features switched on.
+
+{% endcapture %}
+
+{% capture discussion %}
+
+
+{% endcapture %}
+
+{% include templates/task.md %}