diff --git a/_data/tasks.yml b/_data/tasks.yml index a9927d5fbc3b6..61e8918ea6d22 100644 --- a/_data/tasks.yml +++ b/_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: diff --git a/docs/admin/authorization/rbac.md b/docs/admin/authorization/rbac.md index 83649663b6cd6..b1b10d65087f8 100644 --- a/docs/admin/authorization/rbac.md +++ b/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 diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index 930d837ad4870..4427c05ab26dd 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/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: +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: +``` + ### 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/storage-object-in-use-protection.md similarity index 74% rename from docs/tasks/administer-cluster/pvc-protection.md rename to docs/tasks/administer-cluster/storage-object-in-use-protection.md index d6ded3aafb8ed..76b552edfdf4c 100644 --- a/docs/tasks/administer-cluster/pvc-protection.md +++ b/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: +``` + +- 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 %}