add pv protection description (#7620)

_data/tasks.yml

@@ -170,7 +170,7 @@ toc:
   - docs/tasks/administer-cluster/configure-multiple-schedulers.md
   - docs/tasks/administer-cluster/ip-masq-agent.md
   - docs/tasks/administer-cluster/dns-custom-nameservers.md
-  - docs/tasks/administer-cluster/pvc-protection.md
+  - docs/tasks/administer-cluster/storage-object-in-use-protection.md
 
 - title: Federation - Run an App on Multiple Clusters
   section:

docs/admin/authorization/rbac.md

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

docs/concepts/storage/persistent-volumes.md

@@ -72,14 +72,15 @@ Once a user has a claim and that claim is bound, the bound PV belongs to the use
 
 ### Storage Object in Use Protection
 {% assign for_k8s_version="v1.10" %}{% include feature-state-beta.md %}
-The purpose of the Storage Object in Use Protection feature is to ensure that Persistent Volume Claims (PVCs) in active use by a pod are not removed from the system as this may result in data loss.
+The purpose of the Storage Object in Use Protection feature is to ensure that Persistent Volume Claims (PVCs) in active use by a pod and Persistent Volume (PVs) that are bound to PVCs are not removed from the system as this may result in data loss.
 
 **Note:** PVC is in active use by a pod when the pod status is `Pending` and the pod is assigned to a node or the pod status is `Running`.
 {: .note}
 
-When the [Storage Object in Use Protection beta feature](/docs/tasks/administer-cluster/pvc-protection/) 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.
+When the [Storage Object in Use Protection beta feature](/docs/tasks/administer-cluster/storage-object-in-use-protection/) 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, and also if admin deletes a PV that is bound to a PVC, the PV is not removed immediately. PV removal is postponed until the PV is not bound to a PVC any more.
 
 You can see that a PVC is protected when the PVC's status is `Terminating` and the `Finalizers` list includes `kubernetes.io/pvc-protection`:
+
 ```shell
 kubectl describe pvc hostpath
 Name:          hostpath
@@ -94,6 +95,28 @@ Finalizers:    [kubernetes.io/pvc-protection]
 ...
 ```
 
+You can see that a PV is protected when the PV's status is `Terminating` and the `Finalizers` list includes `kubernetes.io/pv-protection` too:
+
+```shell
+kubectl describe pv task-pv-volume
+Name:            task-pv-volume
+Labels:          type=local
+Annotations:     <none>
+Finalizers:      [kubernetes.io/pv-protection]
+StorageClass:    standard
+Status:          Available
+Claim:           
+Reclaim Policy:  Delete
+Access Modes:    RWO
+Capacity:        1Gi
+Message:         
+Source:
+    Type:          HostPath (bare host directory volume)
+    Path:          /tmp/data
+    HostPathType:  
+Events:            <none>
+```
+
 ### 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/storage-object-in-use-protection.md

@@ -8,7 +8,7 @@ title: Storage Object in Use Protection
 {% capture overview %}
 {% assign for_k8s_version="v1.10" %}{% include feature-state-beta.md %}
 
-Persistent volume claims (PVCs) that are in active use by a pod can be protected from pre-mature removal.
+Persistent volume claims (PVCs) that are in active use by a pod and persistent volumes (PVs) that are bound to PVCs can be protected from pre-mature removal.
 
 {% endcapture %}
 
@@ -56,8 +56,9 @@ spec:
 ```
 
 - Check that the PVC has the finalizer `kubernetes.io/pvc-protection` set:
+
 ```shell
-$ kubectl describe pvc slzc
+kubectl describe pvc slzc
 Name:          slzc
 Namespace:     default
 StorageClass:  slow
@@ -215,6 +216,95 @@ Warning  FailedScheduling  18s (x4 over 21s)  default-scheduler  persistentvolum
 
 -  Wait until the pod status of both pods is `Terminated` or `Completed` (either delete the pods or wait until they finish). Afterwards, check that the PVC is removed.
 
+## Storage Object in Use Protection feature used for PV Protection
+
+The example below uses a `HostPath` PV.
+
+Verification scenarios follow below.
+
+### Scenario 1: The PV is not bound to a PVC
+
+- Create a PV:
+
+```yaml
+kind: PersistentVolume
+apiVersion: v1
+metadata:
+  name: task-pv-volume
+  labels:
+    type: local
+spec:
+  capacity:
+    storage: 1Gi
+  accessModes:
+    - ReadWriteOnce
+  persistentVolumeReclaimPolicy: Delete
+  storageClassName: standard
+  hostPath:
+    path: "/tmp/data"
+```
+
+- Check that the PV has the finalizer `kubernetes.io/pv-protection` set:
+
+```shell
+Name:            task-pv-volume
+Labels:          type=local
+Annotations:     pv.kubernetes.io/bound-by-controller=yes
+Finalizers:      [kubernetes.io/pv-protection]
+StorageClass:    standard
+Status:          Terminating (lasts 1m)
+Claim:           default/task-pv-claim
+Reclaim Policy:  Delete
+Access Modes:    RWO
+Capacity:        1Gi
+Message:         
+Source:
+    Type:          HostPath (bare host directory volume)
+    Path:          /tmp/data
+    HostPathType:  
+Events:            <none>
+```
+
+- Delete the PV and check that the PV (not bound to a PVC) is removed successfully.
+
+### Scenario 2: The PV is bound to a PVC
+
+- Again, create the same PV.
+
+- Create a PVC
+
+```yaml
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: task-pv-claim
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 1Gi
+```
+
+- Wait until the PV and PVC are bound to each other.
+- Delete the PV and verify that the PV is not removed but its status is `Terminating`:
+
+```shell
+NAME             CAPACITY     ACCESS MODES   RECLAIM POLICY   STATUS        CLAIM                   STORAGECLASS   REASON    AGE
+task-pv-volume   1Gi          RWO            Delete           Terminating   default/task-pv-claim   standard                 59s
+
+```
+-  Delete the PVC and verify that the PV is removed too.
+
+```shell
+kubectl delete pvc task-pv-claim
+persistentvolumeclaim "task-pv-claim" deleted
+$ kubectl get pvc
+No resources found.
+$ kubectl get pv
+No resources found.
+```
+
 {% endcapture %}
 
 {% capture discussion %}