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

Add docs for implementing resize #5528

Merged
merged 4 commits into from
Sep 25, 2017
Merged

Add docs for implementing resize #5528

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ea8781c
Add docs for implementing resize
gnufied Sep 18, 2017
0ad342a
Update admission-controllers.md
zacharysarah Sep 20, 2017
e10875a
Added link to PVC section
Sep 20, 2017
85ca45c
minor typo fixes
Sep 20, 2017
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
32 changes: 31 additions & 1 deletion docs/admin/admission-controllers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:<nodeName>`.
kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:<nodeName>`.
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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
33 changes: 33 additions & 0 deletions docs/concepts/storage/persistent-volumes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

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

Please consider moving this to the ## PersistentVolumeClaims section.
This article has never touched the concept of PersistentVolumeClaim before that section.

Copy link
Member Author

Choose a reason for hiding this comment

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

hmm, I disagree. Resizing is part of volume's lifecycle and concept of claim has already been introduced. For example from Reclaiming text that appears just above resizing doc:

"When a user is done with their volume, they can delete the PVC objects from the API which allows reclamation of the resource"

So surely users will know about persistent volume claims at this point.

Copy link
Contributor

Choose a reason for hiding this comment

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

The intent of this Alpha feature is about resizing/expanding persistent volumes, but it has to be done via an edit to the corresponding PersistentVolumeClaim. I still suggest we move it down to the PVC subsection so that the logic in this topic flows. But I may be wrong, so I won't insist.


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`.
Copy link
Member

Choose a reason for hiding this comment

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

I would welcome some example here. Either with kubectl edit or kubectl patch. Or should there be a Task for that?


Under no circustances a new `PersistentVolume` gets created to satisfy the claim. Kubernetes will attempt to resize existing volume to satisfy the claim.

Copy link
Member

Choose a reason for hiding this comment

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

I'd add some note that progress of resize can be observed in kubectl describe pvc <name>. Unless it's not implemented yet...


## Types of Persistent Volumes

`PersistentVolume` types are implemented as plugins. Kubernetes currently supports the following plugins:
Expand Down