add statefulset volume expansion kep

keps/NEXT_KEP_NUMBER

@@ -1 +1 @@
-34
+35

keps/sig-apps/0034-20181220-statefulset-volume-expansion.md

@@ -0,0 +1,88 @@
+---
+kep-number: 34
+title: StatefulSet Volume Expansion
+authors:
+  - "@sidakm"
+owning-sig: sig-apps
+participating-sigs:
+  - sig-storage
+reviewers:
+  - "@janetkuo"
+  - "@gnufied"
+approvers:
+  - TBD
+editor: TBD
+creation-date: 2018-12-20
+last-updated: 2018-12-20
+status: provisional
+see-also:
+  - n/a
+replaces:
+  - n/a
+superseded-by:
+  - n/a
+---
+
+# StatefulSet Volume Expansion
+
+## Table of Contents
+
+* [Table of Contents](#table-of-contents)
+* [Summary](#summary)
+* [Motivation](#motivation)
+    * [Goals](#goals)
+* [Proposal](#proposal)
+    * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
+    * [Risks and Mitigations](#risks-and-mitigations)
+* [Graduation Criteria](#graduation-criteria)
+* [Implementation History](#implementation-history)
+
+[Tools for generating]: https://github.com/ekalinin/github-markdown-toc
+
+## Summary
+
+The purpose of this enhancement is to allow for the expansion of persistent volume claims created by StatefulSets. This entails propagating increases to storage requests in `StatefulSets.volumeClaimTemplates` to associated persistent volume claims.
+
+## Motivation
+In Kubernetes v1.11 the persistent volume expansion feature was promoted to beta. This allowed users to expand volumes by editing storage requests in persistent volume claim objects.
+
+Kubernetes creates a persistent volume for each `volumeClaimTemplate` in the `volumeClaimTemplates` component of a StatefulSet. However, it is not possible to expand persistent volumes, created by StatefulSets, by editing the source `volumeClaimTemplate` in the StatefulSet object. Therefore, it is necessary for the user to individually modify all pods' persistent volume claims, by increasing their storage requests, to expand the underlying persistent volumes. This would have to be repeated each time the number of replicas in the StatefulSet object is increased, since new persistent volumes would be created with the original storage request specified in `volumeClaimTemplates` component.
+
+It would be easier and expected to allow for changes to storage requests in the `volumeClaimTemplates` component of a StatefulSet to propagate to all associated persistent volume claims.
+
+Relevant Issues:
+
+* https://github.com/kubernetes/kubernetes/issues/71477
+* https://github.com/kubernetes/kubernetes/issues/72198
+
+### Goals
+
+Allow for increases to storage requests in the `volumeClaimTemplates` component of a StatefulSet to propagate to all associated persistent volume claims.
+
+## Proposal
+
+### Implementation Details/Notes/Constraints
+
+The apiserver will allow for increases to storage requests in the `volumeClaimTemplates` component of a StatefulSet.
+
+During the StatefulSet update process, the StatefulSet controller will detect an update to a `volumeClaimTemplate` by comparing the updated and current revision of the StatefulSet.
+
+While updating a pod, the StatefulSet controller will update a referenced persistent volume claim object if its storage request in the associated `volumeClaimTemplate` has been increased.
+
+The pod will be restarted after the `FileSystemResizePending` condition is True on all updated persistent volume claims it references.
+
+### Risks and Mitigations
+
+Under the `ExpandPersistentVolumes` feature, pods referencing a volume must be restarted for file system expansion to occur after the `FileSystemResizePending` condition is True on the persistent volume claim. If the StatefulSet is configured with the `RollingUpdate` update strategy, then the StatefulSet controller would need to wait for the `FileSystemResizePending` condition to be satisfied on each persistent volume claim referenced by the pod it is updating before restarting the pod. This could noticeably increase the update time of a StatefulSet with many replicas. 
+
+A potential mitigation would be the eventual adoption of the `ExpandInUsePersistentVolumes` alpha feature in Kubernetes v1.11 which enables file system expansion on volumes being used by a pod.  
+
+## Graduation Criteria
+
+Move to Alpha after initial implementation and approvals.
+
+Move to Beta once feature has been in Alpha for a set duration with no issues being reported.
+
+## Implementation History
+
+* Initial implementation [PR](https://github.com/kubernetes/kubernetes/pull/71384/files)