Persistent Volume Claim Protection

PVC Protection alpha feature was added to K8s 1.9 in PRs:
- kubernetes/kubernetes#55824
- kubernetes/kubernetes#55873

and documented in K8s 1.9 in PR:
- kubernetes/website#6415

That's why the PVC Protection is a new alpha feature in OpenShift 3.9 and that's why PVC Protection documentation is added.

Author: pospispa

_topic_map.yml

@@ -395,6 +395,8 @@ Topics:
   File: configuring_vsphere
 - Name: Configuring for local Volume
   File: configuring_local
+- Name: Configuring for Persistent Volume Claim Protection
+  File: configuring_pvc_protection
 - Name: Configuring Persistent Storage
   Dir: persistent_storage
   Distros: openshift-origin,openshift-enterprise

architecture/additional_concepts/storage.adoc

@@ -106,6 +106,41 @@ 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
 xref:pvc-claims-as-volumes[below] for syntax details.
 
+[[pvcprotection]]
+
+=== Persistent Volume Claim Protection
+
+[NOTE]
+====
+Persistent Volume Claim Protection is an alpha feature and may change in a future release of {product-title}.
+====
+
+The purpose of the PVC protection is to ensure that PVCs in active use by a pod are not removed from the system as this may result in data loss.
+
+[NOTE]
+====
+PVC is in active use by a pod when the the pod status is `Pending` and the pod is assigned to a node or the pod status is `Running`.
+====
+
+When the PVC protection feature is enabled, if a user deletes a PVC in active use by a pod, the PVC is not removed immediately. PVC removal is postponed until the PVC is no longer actively used by any pods.
+
+You can see that a PVC is protected when the PVC's status is `Terminating` and the `Finalizers` list includes `kubernetes.io/pvc-protection`:
+[source, shell]
+----
+kubectl describe 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]
+...
+----
+
+
 [[releasing]]
 
 === Releasing

install_config/configuring_pvc_protection.adoc

@@ -0,0 +1,58 @@
+[[install-config-configuring-pvc-protection]]
+= Configuring for Persistent Volume Claim Protection
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+== Overview
+{product-title} can be configured to have
+xref:../architecture/additional_concepts/storage.adoc#pvcprotection[Persistent Volume Claim Protection] feature enabled.
+
+[NOTE]
+====
+Persistent Volume Claim Protection is an alpha feature and may change in a future release of {product-title}.
+====
+
+[[local-volume-enabling-local-volumes]]
+=== Enable Persistent Volume Claim Protection
+Enable the `PVCProtection` feature gate on all masters and nodes.
+
+. Edit or create the master configuration file on all masters (*_/etc/origin/master/master-config.yaml_* by default) and add `PVCProtection=true` under the `apiServerArguments` and `controllerArguments` sections and add `PVCProtection` admission plugin configuration under the `admissionConfig` section:
++
+[source, yaml]
+----
+admissionConfig:
+  pluginConfig:
+    PVCProtection:
+      configuration:
+        apiVersion: v1
+        disable: false
+        kind: DefaultAdmissionConfig
+...
+kubernetesMasterConfig:
+...
+  apiServerArguments:
+    feature-gates:
+    - PVCProtection=true
+...
+  controllerArguments:
+    feature-gates:
+    - PVCProtection=true
+...
+----
+
+. On all nodes, edit or create the node configuration file (*_/etc/origin/node/node-config.yaml_* by default)  and add `PVCProtection=true` fetaure gate under `kubeletArguments`.
++
+[source, yaml]
+----
+kubeletArguments:
+   feature-gates:
+     - PVCProtection=true
+----
+
+. On all masters and nodes, restart OpenShift for the changes to take effect.