Merge pull request #581 from msau42/update-docs

Update local volume docs with version compatibility, reorg known issues

local-volume/KNOWN_ISSUES.md

@@ -0,0 +1,38 @@
+# Known Issues and Limitations
+
+## K8s
+
+### 1.9: Alpha
+
+* If you prebind a PVC (by setting PVC.VolumeName) at the same time that another
+Pod is being scheduled, it's possible that the Pod's PVCs will encounter a partial
+binding failure. Manual recovery is needed in this situation.
+ * Workarounds:
+ * Don't prebind PVCs and have Kubernetes bind volumes for the same
+ StorageClass.
+ * Prebind PV upon creation instead.
+
+### 1.7: Alpha
+
+* Multiple local PVCs in a single pod.
+ * Fixed in 1.9.
+ * No known workarounds.
+* PVC binding does not consider pod scheduling requirements and may make
+ suboptimal or incorrect decisions.
+ * Fixed in 1.9.
+ * Workarounds:
+ * Run your pods that require local storage first.
+ * Give your pods high priority.
+ * Run a workaround controller that unbinds PVCs for pods that are
+ stuck pending.
+
+## Provisioner
+
+### 1.0:
+* The provisioner will not correctly detect new mounts added after it has been started.
+ The local PV capacity will be reported as the root filesystem capacity.
+ * Fixed with provisioner 2.0 + K8s 1.8. Requires mount propagation alpha
+ feature.
+ * Workaround:
+ * Before adding any new mount points, stop the provisioner daemonset, add the
+ new mount points, start the daemonset.

local-volume/README.md

@@ -22,66 +22,28 @@ directories by creating and cleaning up PersistentVolumes for each volume.
 * The static provisioner only discovers mount points. For directory-based local
  volumes, they must be bind-mounted into the discovery directories.
 
-## Feature Status
+## K8s Feature Status
+
+Also see [known issues](KNOWN_ISSUES.md) and [provisioner CHANGELOG](provisioner/CHANGELOG.md).
 
 ### 1.9: Alpha
 
-**Important:** `PersistentLocalVolumes`, `VolumeScheduling`, and
-`MountPropagation` [feature gates must be enabled starting in 1.9](#enabling-the-alpha-feature-gates).
-
-What works:
-* Everything in 1.7.
-* New StorageClass `volumeBindingMode` parameter that fixes the previous
- issues:
- * Multiple local PVCs in a single pod.
- * PVC binding is delayed until pod scheduling and takes into account all the
- pod's scheduling requirements.
-
-What doesn't work:
-* If you prebind a PVC (by setting PVC.VolumeName) at the same time that another
-Pod is being scheduled, it's possible that the Pod's PVCs will encounter a partial
-binding failure. Manual recovery is needed in this situation.
- * Workarounds:
- * Don't prebind PVCs and have Kubernetes bind volumes for the same
- StorageClass.
- * Prebind PV upon creation instead.
+* New StorageClass `volumeBindingMode` parameter that will delay PVC binding
+ until a pod is scheduled.
 
 ### 1.7: Alpha
 
-What works:
-* Create a PV specifying a directory with node affinity.
+* New `local` PersistentVolume source that allows specifying a directory or mount
+ point with node affinity.
 * Pod using the PVC that is bound to this PV will always get scheduled to that node.
-* External static provisioner DaemonSet that discovers local directories,
- creates, cleans up and deletes PVs.
-
-What doesn't work and workarounds:
-* Multiple local PVCs in a single pod.
- * Goal for 1.9.
- * No known workarounds.
-* PVC binding does not consider pod scheduling requirements and may make
- suboptimal or incorrect decisions.
- * Goal for 1.9.
- * Workarounds:
- * Run your pods that require local storage first.
- * Give your pods high priority.
- * Run a workaround controller that unbinds PVCs for pods that are
- stuck pending. TODO: add link
-* The provisioner will not correctly detect mounts added after it
- has been started without mount propogation.
- * This issue is resolved in provisioner 2.0 when the mount propagation
- alpha feature gate is enabled, which is available in Kubernetes 1.8+.
- * The provisioner 1.x will detect the existance of a new directory in the
- discovery directory. Then, it will incorrectly create a local PV with
- the root filesystem capacity. 
- * Provisioner 1.x workaround: Before adding any new mount points, stop
- the provisioner daemonset, add the new mount points, start the daemonset.
 
 ### Future features
-* Local block devices as a volume source, with partitioning and fs formatting
+
 * Pod accessing local raw block device
+* Local block devices as a volume source, with partitioning and fs formatting
+* Dynamic provisioning for shared local persistent storage
 * Local PV health monitoring, taints and tolerations
 * Inline PV (use dedicated local disk as ephemeral storage)
-* Dynamic provisioning for shared local persistent storage
 
 ## User Guide
 

local-volume/provisioner/CHANGELOG.md

@@ -1,12 +1,12 @@
-# v2.0.0
+# [v2.0.0](https://github.com/kubernetes-incubator/external-storage/releases/tag/local-volume-provisioner-v2.0.0)
 This version is incompatible and has breaking changes with v1!
 * Remove default config, a configmap is now required.
 * Configmap data is changed from json to yaml syntax.
 * All local volumes must be mount points. For directory-based volumes, a
- bind-mount must be done in order for the provisioner to discover them.
+ bind-mount must be done in order for the provisioner to discover them. This
+ requires the K8s [mount propgataion feature](https://kubernetes.io/docs/concepts/storage/volumes/#mount-propagation)
+ to be enabled.
 * Detected capacity is rounded down to the nearest GB.
-* [Mount propagation](https://kubernetes.io/docs/concepts/storage/volumes/#mount-propagation)
- is required to discover new mount points after the provisioner has started.
 * New option to specify which node labels to add to the PV.
 
 # [v1.0.1](https://github.com/kubernetes-incubator/external-storage/releases/tag/local-volume-provisioner-bootstrap-v1.0.1)