Persistent storage proposal

persistent-storage.md

@@ -0,0 +1,85 @@
+# PersistentVolume
+
+This document proposes a model for managing persistent, cluster-scoped storage for applications requiring long lived data.
+
+### tl;dr
+
+Two new API kinds:
+
+A `PersistentVolume` is created by a cluster admin and is a piece of persistent storage exposed as a volume.  It is analogous to a node.
+
+A `PersistentVolumeClaim` is a user's request for a persistent volume to use in a pod. It is analogous to a pod.  
+
+One new system component:
+
+`PersistentVolumeManager` watches for new volumes to manage in the system, analogous to the node controller.  The volume manager also watches for claims by users and binds them to available volumes. This 
+component is a singleton that manages all persistent volumes in the cluster.
+
+Kubernetes makes no guarantees at runtime that the underlying storage exists or is available.  High availability is left to the storage provider.
+
+### Goals
+
+* Allow administrators to describe available storage
+* Allow pod authors to discover and request persistent volumes to use with pods
+* Enforce security through access control lists and securing storage to the same namespace as the pod volume
+* Enforce quotas through admission control
+* Enforce scheduler rules by resource counting
+* Ensure developers can rely on storage being available without being closely bound to a particular disk, server, network, or storage device.
+
+
+#### Describe available storage
+
+Cluster adminstrators use the API to manage *PersistentVolumes*.  The singleton PersistentVolumeManager watches the Kubernetes API for new volumes and adds them to its internal cache of volumes in the system.
+All persistent volumes are managed and made available by the volume manager.  The manager also watches for new claims for storage and binds them to an available, matching volume.
+
+Many means of dynamic provisioning will be eventually be implemented for various storage types. 
+
+```
+
+	$ cluster/kubectl.sh get pv
+
+```
+
+##### API Implementation:
+
+| Action | HTTP Verb | Path | Description |
+| ---- | ---- | ---- | ---- |
+| CREATE | POST | /api/{version}/persistentvolumes/ | Create instance of PersistentVolume in system namespace  |
+| GET | GET | /api/{version}persistentvolumes/{name} | Get instance of PersistentVolume in system namespace with {name} |
+| UPDATE | PUT | /api/{version}/persistentvolumes/{name} | Update instance of PersistentVolume in system namespace with {name} |
+| DELETE | DELETE | /api/{version}/persistentvolumes/{name} | Delete instance of PersistentVolume in system namespace with {name} |
+| LIST | GET | /api/{version}/persistentvolumes | List instances of PersistentVolume in system namespace |
+| WATCH | GET | /api/{version}/watch/persistentvolumes | Watch for changes to a PersistentVolume in system namespace |
+
+
+
+#### Request Storage
+
+
+Kubernetes users request a persistent volume for their pod by creating a *PersistentVolumeClaim*.  Their request for storage is described by their requirements for resource and mount capabilities.
+
+Requests for volumes are bound to available volumes by the volume manager, if a suitable match is found.  Requests for resources can go unfulfilled.
+
+Users attach their claim to their pod using a new *PersistentVolumeClaimVolumeSource* volume source.
+
+
+##### Users require a full API to manage their claims.
+
+
+| Action | HTTP Verb | Path | Description |
+| ---- | ---- | ---- | ---- |
+| CREATE | POST | /api/{version}/ns/{ns}/persistentvolumeclaims/ | Create instance of PersistentVolumeClaim in namespace {ns} |
+| GET | GET | /api/{version}/ns/{ns}/persistentvolumeclaims/{name} | Get instance of PersistentVolumeClaim in namespace {ns} with {name} |
+| UPDATE | PUT | /api/{version}/ns/{ns}/persistentvolumeclaims/{name} | Update instance of PersistentVolumeClaim in namespace {ns} with {name} |
+| DELETE | DELETE | /api/{version}/ns/{ns}/persistentvolumeclaims/{name} | Delete instance of PersistentVolumeClaim in namespace {ns} with {name} |
+| LIST | GET | /api/{version}/ns/{ns}/persistentvolumeclaims | List instances of PersistentVolumeClaim in namespace {ns} |
+| WATCH | GET | /api/{version}/watch/ns/{ns}/persistentvolumeclaims | Watch for changes to PersistentVolumeClaim in namespace {ns} |
+
+
+
+#### Scheduling constraints
+
+Scheduling constraints are to be handled similar to pod resource constraints.  Pods will need to be annotated or decorated with the number of resources it requires on a node.  Similarly, a node will need to list how many it has used or available.
+
+TBD
+