Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add docs for volume expansion and online resizing #8896

Merged
merged 3 commits into from
Jun 11, 2018
Merged

Add docs for volume expansion and online resizing #8896

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9c212cd
Add docs for volume expansion going beta
gnufied Jun 4, 2018
c7e930d
Copyedit
Jun 5, 2018
19e7d55
Address feedback
Jun 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 32 additions & 15 deletions content/en/docs/concepts/storage/persistent-volumes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,20 +167,21 @@ However, the particular path specified in the custom recycler pod template in th

### Expanding Persistent Volumes Claims

Kubernetes 1.8 added Alpha support for expanding persistent volumes. In v1.9, the following volume types support expanding Persistent volume claims:
{{< feature-state for_k8s_version="v1.8" state="alpha" >}}
{{< feature-state for_k8s_version="v1.11" state="beta" >}}
Support for expanding PersistentVolumeClaims (PVCs) is now enabled by default. You can expand
the following types of volumes:

* gcePersistentDisk
* awsElasticBlockStore
* Cinder
* glusterfs
* rbd
* Azure File
* Azure Disk
* Portworx

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.
You can only expand a PVC if its storage class's `allowVolumeExpansion` field is set to true.

``` yaml
kind: StorageClass
Expand All @@ -196,17 +197,33 @@ parameters:
allowVolumeExpansion: true
```

Once both feature gate and the aforementioned admission plug-in are turned on, a user can request larger volume for their `PersistentVolumeClaim`
by simply editing the claim and requesting a larger size. This in turn will trigger expansion of the volume that is backing the underlying `PersistentVolume`.
To request a larger volume for a PVC, edit the PVC's configuration and request a larger
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure I would use wording "edit the PVC's configuration" to refer editing the pvc's yaml - I was thinking something like "edit PVC object" would be better?

size. This triggers expansion of the volume that backs the underlying `PersistentVolume`. A
new `PersistentVolume` is never created to satisfy the claim. Instead, an existing volume is resized.

#### Resizing a volume containing a file system

You can only resize volumes containing a file system if the file system is XFS, Ext3, or Ext4.

When a volume contains a file system, the file system is only resized when a new Pod is started using
the `PersistentVolumeClaim` in ReadWrite mode. Therefore, if a pod or deployment is using a volume and
you want to expand it, you need to delete or recreate the pod after the volume has been exxpanded by the cloud provider in the controller-manager. You can check the status of resize operation by running the `kubectl describe pvc` command:

```
kubectl describe pvc <pvc_name>
```

If the `PersistentVolumeClaim` has the status `FileSystemResizePending`, it is safe to recreate the pod using the PersistentVolumeClaim.

Under no circumstances will a new `PersistentVolume` be created to satisfy the claim. Kubernetes will instead attempt to resize the existing volume.
#### Resizing an in-use PersistentVolumeClaim

For expanding volumes containing a file system, file system resizing is only performed when a new Pod is started using the `PersistentVolumeClaim` in
ReadWrite mode. In other words, if a volume being expanded is used in a pod or deployment, you will need to delete and recreate the pod for file system
resizing to take place. Also, file system resizing is only supported for following file system types:
{{< feature-state for_k8s_version="v1.11" state="alpha" >}}

* XFS
* Ext3, Ext4
Expanding in-use PVCs is an alpha feature. To use it, enable the `ExpandInUsePersistentVolumes` feature gate.
In this case, you don't need to delete and recreate a Pod or deployment that is using an existing PVC.
Any in-use PVC automatically becomes available to its Pod as soon as its file system has been expanded.
This feature has no effect on PVCs that are not in use by a Pod or deployment. You must create a Pod which
uses the PVC before the expansion can complete.

{{< note >}}
**Note:** Expanding EBS volumes is a time consuming operation. Also, there is a per-volume quota of one modification every 6 hours.
Expand Down