From a6eb85887d0060c50e5ec8c0f935dc5a2d9155af Mon Sep 17 00:00:00 2001 From: Pavel Pospisil Date: Thu, 7 Dec 2017 21:44:53 +0100 Subject: [PATCH] Postpone Deletion of a Persistent Volume Claim in case It Is Used by a Pod (#6415) * Postpone Deletion of a Persistent Volume Claim in case It Is Used by a Pod A new feature PVC Protection was added into K8s 1.9 that's why this documentation change is needed. * Added tag at the top of each new area. * Fix typo * Fix: switched on in (all kubelets) -> (all K8s components). * Added link to admission controller * Moved PVC Protection configuration into Before you begin section. * Added steps how to verify PVC Protection feature. * Fixes for admission controller plugin description and for PVC Protection description in PVC lifecycle. * Testing official rendering of enumerations (1., 2., 3., etc.) * Re-write to address comments from review. * Fixed definition when a PVC is in active use by a pod. --- _data/tasks.yml | 1 + docs/admin/admission-controllers.md | 4 + docs/admin/authorization/rbac.md | 1 + docs/concepts/storage/persistent-volumes.md | 23 +++ .../administer-cluster/pvc-protection.md | 144 ++++++++++++++++++ 5 files changed, 173 insertions(+) create mode 100644 docs/tasks/administer-cluster/pvc-protection.md diff --git a/_data/tasks.yml b/_data/tasks.yml index b7defe6768..48aa4425df 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -169,6 +169,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 - title: Federation - Run an App on Multiple Clusters section: diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md index cdf99f30f9..572a79d9cd 100644 --- a/docs/admin/admission-controllers.md +++ b/docs/admin/admission-controllers.md @@ -329,6 +329,10 @@ 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 (alpha) +{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %} +The `PVCProtection` plugin adds the `kubernetes.io/pvc-protection` finalizer to newly created Persistent Volume Claims (PVCs). In case a user deletes a PVC the PVC is not removed until the finalizer is removed from the PVC by PVC Protection Controller. Refer to the [PVC Protection](/docs/concepts/storage/persistent-volumes/#persistent-volume-claim-protection) for more detailed information. + ### 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 07d5b6f1b4..a2222b8822 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: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 834f695c10..059202db28 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -70,6 +70,29 @@ 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 +{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %} +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 alpha 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. + +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 described pvc hostpath +Name: hostpath +Namespace: default +StorageClass: example-hostpath +Status: Terminating +Volume: +Labels: +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 0000000000..0c1ee061c0 --- /dev/null +++ b/docs/tasks/administer-cluster/pvc-protection.md @@ -0,0 +1,144 @@ +--- +approvers: +- msau42 +- jsafrane +title: Persistent Volume Claim Protection +--- + +{% capture overview %} +{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %} + +As of Kubernetes 1.9, persistent volume claims (PVCs) that are in active use by a pod can be protected from pre-mature removal. + +{% endcapture %} + +{% capture prerequisites %} + +- A v1.9 or higher Kubernetes must be installed. +- As PVC Protection is a Kubernetes v1.9 alpha feature it must be enabled: +1. [Admission controller](/docs/admin/admission-controllers/) must be started with the [PVC Protection plugin](/docs/admin/admission-controllers/#persistent-volume-claim-protection-alpha). +2. All Kubernetes components must be started with the `PVCProtection` alpha features enabled. + +{% endcapture %} + +{% capture steps %} + +## PVC Protection Verification + +The example below uses a GCE PD `StorageClass`, however, similar steps can be performed for any volume type. + +Create a `StorageClass` for convenient storage provisioning: +```yaml +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: slow +provisioner: kubernetes.io/gce-pd +parameters: + type: pd-standard +``` + +There are two scenarios: a PVC deleted by a user is either in active use or not in active use by a pod. + +### Scenario 1: The PVC is not in active use by a pod + +- Create a PVC: + +```yaml +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: slzc +spec: + accessModes: + - ReadWriteOnce + storageClassName: slow + resources: + requests: + storage: 3.7Gi +``` + +- Check that the PVC has the finalizer `kubernetes.io/pvc-protection` set: +```shell +$ kubectl describe pvc slzc +Name: slzc +Namespace: default +StorageClass: slow +Status: Bound +Volume: pvc-bee8c30a-d6a3-11e7-9af0-42010a800002 +Labels: +Annotations: pv.kubernetes.io/bind-completed=yes + pv.kubernetes.io/bound-by-controller=yes + volume.beta.kubernetes.io/storage-provisioner=kubernetes.io/gce-pd +Finalizers: [kubernetes.io/pvc-protection] +Capacity: 4Gi +Access Modes: RWO +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal ProvisioningSucceeded 2m persistentvolume-controller Successfully provisioned volume pvc-bee8c30a-d6a3-11e7-9af0-42010a800002 using kubernetes.io/gce-pd +``` + +- Delete the PVC and check that the PVC (not in active use by a pod) was removed successfully. + +### Scenario 2: The PVC is in active use by a pod + +- Again, create the same PVC. +- Create a pod that uses the PVC: + +```yaml +kind: Pod +apiVersion: v1 +metadata: + name: app1 +spec: + containers: + - name: test-pod + image: gcr.io/google_containers/busybox:1.24 + command: + - "/bin/sh" + args: + - "-c" + - "date > /mnt/app1.txt; sleep 60 && exit 0 || exit 1" + volumeMounts: + - name: path-pvc + mountPath: "/mnt" + restartPolicy: "Never" + volumes: + - name: path-pvc + persistentVolumeClaim: + claimName: slzc +``` + +- Wait until the pod status is `Running`, i.e. the PVC becomes in active use. +- Delete the PVC that is now in active use by a pod and verify that the PVC is not removed but its status is `Terminating`: + +```shell +Name: slzc +Namespace: default +StorageClass: slow +Status: Terminating (since Fri, 01 Dec 2017 14:47:55 +0000) +Volume: pvc-803a1f4d-d6a6-11e7-9af0-42010a800002 +Labels: +Annotations: pv.kubernetes.io/bind-completed=yes + pv.kubernetes.io/bound-by-controller=yes + volume.beta.kubernetes.io/storage-provisioner=kubernetes.io/gce-pd +Finalizers: [kubernetes.io/pvc-protection] +Capacity: 4Gi +Access Modes: RWO +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal ProvisioningSucceeded 52s persistentvolume-controller Successfully provisioned volume pvc-803a1f4d-d6a6-11e7-9af0-42010a800002 using kubernetes.io/gce-pd +``` +- Wait until the pod status is `Terminated` (either delete the pod or wait until it finishes). Afterwards, check that the PVC is removed. + + +{% endcapture %} + +{% capture discussion %} + + +{% endcapture %} + +{% include templates/task.md %}