Merge pull request #7577 from tmorriso-rh/pospispa-566-postpone-pvc-deletion-if-used-in-a-pod

Traci Morrison · web-flow · commit 513488c8dc27 · 2018-02-13T08:39:11.000-05:00
Trello: Pospispa 566 postpone pvc deletion if used in a pod
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -395,8 +395,10 @@ Topics:
   Distros: openshift-origin,openshift-enterprise
 - Name: Configuring for VMWare vSphere
   File: configuring_vsphere
-- Name: Configuring for local Volume
+- 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
diff --git a/architecture/additional_concepts/storage.adoc b/architecture/additional_concepts/storage.adoc
@@ -106,8 +106,42 @@ 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.
 
-[[releasing]]
+[[pvcprotection]]
+=== Persistent Volume Claim Protection
+
+[NOTE]
+====
+PVC protection is an alpha feature and may change in a future release of {product-title}.
+====
+
+The purpose of 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]
+====
+A 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 immediately removed. 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]
+...
+----
 
+To enable PVC protection, see xref:../../install_config/configuring_pvc_protection.adoc#install-config-configuring-pvc-protection[Configuring Persistent Volume Claim Protection].
+
+[[releasing]]
 === Releasing
 
 When a user is done with a volume, they can delete the PVC object from the API
@@ -138,7 +172,7 @@ If supported by appropriate volume plug-in, recycling performs a basic scrub (`r
 
 [WARNING]
 ====
-The `recycle` reclaim policy is deprecated in favor of dynamic provisioning and it will be removed in future releases.
+The `recycle` reclaim policy is deprecated in favor of dynamic provisioning and is removed starting in {product-title} 3.6.
 ====
 
 ifdef::openshift-origin,openshift-enterprise[]
@@ -255,7 +289,7 @@ Future attributes may include IOPS, throughput, etc.
 === Access Modes
 
 A `PersistentVolume` can be mounted on a host in any way supported by the
-resource provider. Providers will have different capabilities and each PV's
+resource provider. Providers have different capabilities and each PV's
 access modes are set to the specific modes supported by that particular volume.
 For example, NFS can support multiple read/write clients, but a specific NFS PV
 might be exported on the server as read-only. Each PV gets its own set of access
@@ -317,7 +351,7 @@ Before draining the node, first ensure the pods that use these volumes are
 deleted.
 ====
 
-The table below lists the access modes supported by different persistent volumes:
+The table below lists the access modes supported by different PVs:
 
 .Supported Access Modes for Persistent Volumes
 [cols=",^v,^v,^v", width="100%",options="header"]
@@ -347,7 +381,7 @@ ifdef::openshift-dedicated,openshift-online[]
 
 === {product-title} Restrictions
 
-The following restrictions apply when using persistent volumes with {product-title}:
+The following restrictions apply when using PVs with {product-title}:
 endif::[]
 
 ifdef::openshift-dedicated[]
@@ -370,7 +404,7 @@ ifdef::openshift-online[]
    ** VOLUME directive without a mapped external volume fails to be instantiated.
  * *emptyDir* is restricted to 512 Mi per project (group) per node.
    ** If there is a single pod for a project on a particular node, then the pod can consume up to 512 Mi of *emptyDir* storage.
-   ** If there are multiple pods for a project on a particular node, then those pods will share the 512 Mi of *emptyDir* storage.
+   ** If there are multiple pods for a project on a particular node, then those pods share the 512 Mi of *emptyDir* storage.
  *  *emptyDir* has the same lifecycle as the pod:
    ** *emptyDir* volumes survive container crashes/restarts.
    ** *emptyDir* volumes are deleted when the pod is deleted.
@@ -404,7 +438,7 @@ Currently, only NFS and HostPath support the 'Recycle' reclaim policy.
 
 [WARNING]
 ====
-The `recycle` reclaim policy is deprecated in favor of dynamic provisioning and it will be removed in future releases.
+The `recycle` reclaim policy is deprecated in favor of dynamic provisioning and is removed starting in {product-title} 3.6.
 ====
 
 [[pv-phase]]
@@ -440,7 +474,7 @@ ifdef::openshift-enterprise,openshift-origin[]
 === Mount Options
 [IMPORTANT]
 ====
-Mount Options is a Technology Preview feature and it is only available for manually provisioned persistent volumes.
+Mount Options is a Technology Preview feature and it is only available for manually provisioned PVs.
 ifdef::openshift-enterprise[]
 Technology Preview features are not supported with Red Hat production service
 level agreements (SLAs), might not be functionally complete, and Red Hat does
@@ -453,7 +487,7 @@ https://access.redhat.com/support/offerings/techpreview/.
 endif::[]
 ====
 
-You can specify mount options while mounting a persistent volume by using the annotation `volume.beta.kubernetes.io/mount-options`.
+You can specify mount options while mounting a PV by using the annotation `volume.beta.kubernetes.io/mount-options`.
 
 For example:
 
@@ -478,9 +512,9 @@ spec:
     name: claim1
     namespace: default
 ----
-<1> Specified mount options are then used while mounting the persistent volume to the disk.
+<1> Specified mount options are then used while mounting the PV to the disk.
 
-The following persistent volume types support mount options:
+The following PV types support mount options:
 
 - NFS
 - GlusterFS
@@ -495,7 +529,7 @@ The following persistent volume types support mount options:
 
 [NOTE]
 ====
-Fibre Channel and HostPath persistent volumes do not support mount options.
+Fibre Channel and HostPath PVs do not support mount options.
 ====
 endif::openshift-enterprise,openshift-origin[]
 [[persistent-volume-claims]]
@@ -584,7 +618,7 @@ ifdef::openshift-enterprise,openshift-origin[]
 == Block Volume Support
 [IMPORTANT]
 ====
-Block Volume Support is a Technology Preview feature and it is only available for manually provisioned persistent volumes.
+Block Volume Support is a Technology Preview feature and it is only available for manually provisioned PVs.
 ifdef::openshift-enterprise[]
 Technology Preview features are not supported with Red Hat production service
 level agreements (SLAs), might not be functionally complete, and Red Hat does
@@ -635,7 +669,7 @@ spec:
     requests:
       storage: 10Gi
 ----
-<1> `volumeMode` field indicating that a raw block persistent volume is requested.
+<1> `volumeMode` field indicating that a raw block PV is requested.
 
 .Example Pod Specification
 [source, yaml]
diff --git a/install_config/configuring_pvc_protection.adoc b/install_config/configuring_pvc_protection.adoc
@@ -0,0 +1,62 @@
+[[install-config-configuring-pvc-protection]]
+= Configuring Persistent Volume Claim Protection
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+== Overview
+{product-title} can be configured to have the
+xref:../architecture/additional_concepts/storage.adoc#pvcprotection[persistent
+volume claim (PVC) protection] feature enabled. This feature ensures that PVCs
+in active use by a pod are not removed from the system, as this may result in
+data loss.
+
+[NOTE]
+====
+PVC protection is an alpha feature and may change in a future release of {product-title}.
+====
+
+[[local-volume-enabling-local-volumes]]
+=== Enable PVC Protection
+
+To 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). 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 the `PVCProtection=true` feature gate under `kubeletArguments`:
++
+[source, yaml]
+----
+kubeletArguments:
+  feature-gates:
+  - PVCProtection=true
+----
+
+. On all masters and nodes, restart {product-title} for the changes to take effect.
