From 6ff373e1d9b2456eaab2edb29793fde46bc087b2 Mon Sep 17 00:00:00 2001 From: Hemant Kumar Date: Mon, 25 Sep 2017 16:14:11 -0400 Subject: [PATCH] Add docs for implementing resize (#5528) * Add docs for implementing resize * Update admission-controllers.md * Added link to PVC section * minor typo fixes --- docs/admin/admission-controllers.md | 32 +++++++++++++++++++- docs/concepts/storage/persistent-volumes.md | 33 +++++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md index e25bc55fcb506..a5deca8ad5d26 100644 --- a/docs/admin/admission-controllers.md +++ b/docs/admin/admission-controllers.md @@ -280,7 +280,7 @@ namespace. In order to enforce integrity of that process, we strongly recommend ### NodeRestriction This plug-in limits the `Node` and `Pod` objects a kubelet can modify. In order to be limited by this admission plugin, -kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:`. +kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:`. Such kubelets will only be allowed to modify their own `Node` API object, and only modify `Pod` API objects that are bound to their node. Future versions may add additional restrictions to ensure kubelets have the minimal set of permissions required to operate correctly. @@ -332,6 +332,35 @@ metadata: name: namespace3 ``` +### PersistentVolumeClaimResize + +This plug-in implements additional validations for checking incoming `PersistentVolumeClaim` resize requests. +**Note:** Support for volume resizing is available as an alpha feature. Admins must set the feature gate `ExpandPersistentVolumes` +to `true` to enable resizing. +{: .note} + +After enabling the `ExpandPersistentVolumes` feature gate, enabling the `PersistentVolumeClaimResize` admission +plug-in is recommended, too. This plug-in prevents resizing of all claims by default unless a claim's `StorageClass` + explicitly enables resizing by setting `allowVolumeExpansion` to `true`. + +For example: all `PersistnetVolumeClaim`s created from the following `StorageClass` support volume expansion: + +```yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: gluster-vol-default +provisioner: kubernetes.io/glusterfs +parameters: + resturl: "http://192.168.10.100:8080" + restuser: "" + secretNamespace: "" + secretName: "" +allowVolumeExpansion: true +``` + +For more information about persistent volume claims, see ["PersistentVolumeClaims"](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims). + ### PodPreset This plug-in injects a pod with the fields specified in a matching PodPreset. @@ -387,6 +416,7 @@ This plug-in will deny any pod that attempts to set certain escalating [Security This plug-in implements automation for [serviceAccounts](/docs/user-guide/service-accounts). We strongly recommend using this plug-in if you intend to make use of Kubernetes `ServiceAccount` objects. + ## Is there a recommended set of plug-ins to use? Yes. diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index f36fdceaf7873..f0db8975b49a0 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -109,6 +109,39 @@ However, the particular path specified in the custom recycler pod template in th For volume plugins that support the Delete reclaim policy, deletion removes both the `PersistentVolume` object from Kubernetes, as well as deleting the associated storage asset in the external infrastructure, such as an AWS EBS, GCE PD, Azure Disk, or Cinder volume. Volumes that were dynamically provisioned inherit the [reclaim policy of their `StorageClass`](#reclaim-policy-1), which defaults to Delete. The administrator should configure the `StorageClass` according to users' expectations, otherwise the PV must be edited or patched after it is created. See [Change the Reclaim Policy of a PersistentVolume](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/). + +### Expanding Persistent Volumes Claims + +With Kubernetes 1.8, we have added Alpha support for expanding persistent volumes. The current Alpha support was designed to only support volume types +that don't need file system resizing (Currently only glusterfs). + +Administrator can allow expanding persistent volume claims by setting `ExpandPersistentVolumes` feature gate to true. Administrator +should also enable [`PersistentVolumeClaimResize` admission plugin](/docs/admin/admission-controllers/#persistentvolumeclaimresize) +to perform additional validations of volumes that can be resized. + +Once `PersistentVolumeClaimResize` admission plug-in has been turned on, resizing will only be allowed for storage classes +whose `allowVolumeExpansion` field is set to true. + +``` yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: gluster-vol-default +provisioner: kubernetes.io/glusterfs +parameters: + resturl: "http://192.168.10.100:8080" + restuser: "" + secretNamespace: "" + secretName: "" +allowVolumeExpansion: true +``` + +Once both feature gate and aforementioned admission plug-in are turned on, an user can request larger volume for their `PersistentVolumeClaim` +by simply editing the claim and requesting bigger size. This in turn will trigger expansion of volume that is backing underlying `PersistentVolume`. + +Under no circustances a new `PersistentVolume` gets created to satisfy the claim. Kubernetes will attempt to resize existing volume to satisfy the claim. + + ## Types of Persistent Volumes `PersistentVolume` types are implemented as plugins. Kubernetes currently supports the following plugins: