From a54be1fdaf58fbc359e1e6b1d29165ea47ff59b3 Mon Sep 17 00:00:00 2001
From: pospispa <ppospisi@redhat.com>
Date: Wed, 22 Nov 2017 20:23:32 +0100
Subject: [PATCH] WIP: Postpone Deletion of a Persistent Volume Claim in case
 It Is Used by a Pod Documentation

---
 docs/admin/admission-controllers.md           |  5 +++
 docs/admin/authorization/rbac.md              |  1 +
 docs/concepts/storage/persistent-volumes.md   | 18 ++++++++++
 .../administer-cluster/pvc-protection.md      | 36 +++++++++++++++++++
 4 files changed, 60 insertions(+)
 create mode 100644 docs/tasks/administer-cluster/pvc-protection.md

diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md
index cdf99f30f95ef..34f90403c64c3 100644
--- a/docs/admin/admission-controllers.md
+++ b/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
diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md
index f387f44456cd3..b2dc50f9c1cdf 100644
--- a/docs/admin/authorization/rbac.md
+++ b/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
diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md
index 4dccc7bc75161..06c88e225332f 100644
--- a/docs/concepts/storage/persistent-volumes.md
+++ b/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.
diff --git a/docs/tasks/administer-cluster/pvc-protection.md b/docs/tasks/administer-cluster/pvc-protection.md
new file mode 100644
index 0000000000000..f98eb80051d2d
--- /dev/null
+++ b/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 %}