From e3436df7b4cf93b3aac6ef42c1923fbe9feefe8d Mon Sep 17 00:00:00 2001 From: Michelle Au Date: Tue, 30 Jan 2018 14:40:00 -0800 Subject: [PATCH] Reorg local volume known issues and versions for fixes --- local-volume/KNOWN_ISSUES.md | 38 ++++++++++++++++++ local-volume/README.md | 58 +++++---------------------- local-volume/provisioner/CHANGELOG.md | 8 ++-- 3 files changed, 52 insertions(+), 52 deletions(-) create mode 100644 local-volume/KNOWN_ISSUES.md diff --git a/local-volume/KNOWN_ISSUES.md b/local-volume/KNOWN_ISSUES.md new file mode 100644 index 00000000000..6912f2bf026 --- /dev/null +++ b/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. diff --git a/local-volume/README.md b/local-volume/README.md index 12ff76f220c..30f16433427 100644 --- a/local-volume/README.md +++ b/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 diff --git a/local-volume/provisioner/CHANGELOG.md b/local-volume/provisioner/CHANGELOG.md index cec63d8f1f5..fb23af5a7ad 100644 --- a/local-volume/provisioner/CHANGELOG.md +++ b/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)