ephemeral volumes in Kubernetes 1.16

The CSIDriverInfo object was extended and the feature changed from
alpha to beta.

Author: pohly

book/src/csi-driver-object.md

@@ -26,6 +26,9 @@ metadata:
 spec:
   attachRequired: true
   podInfoOnMount: true
+  volumeLifecycleModes: # added in Kubernetes 1.16
+  - Persistent
+  - Ephemeral
 ```
 
 There are three important fields:
@@ -45,6 +48,13 @@ There are three important fields:
     * `"csi.storage.k8s.io/pod.namespace": pod.Namespace`
     * `"csi.storage.k8s.io/pod.uid": string(pod.UID)`
   * For more information see [Pod Info on Mount](pod-info.md).
+* `volumeLifecycleModes`
+  * This field was added in Kubernetes 1.16 and cannot be set when using an older Kubernetes release.
+  * It informs Kubernetes about the volume modes that are supported by the driver.
+    This ensures that the driver [is not used incorrectly](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/20190122-csi-inline-volumes.md#support-for-inline-csi-volumes) by Kubernetes.
+    The default is `Persistent`, which is the normal PVC/PV mechanism. `Ephemeral` enables
+    [inline ephemeral volumes](ephemeral-local-volumes.md) in addition (when both
+    are listed) or instead of normal volumes (when it is the only entry in the list).
 
 ## What creates the CSIDriver object?
 
@@ -64,28 +74,31 @@ Using the `CSIDriver` object, it is now possible to query Kubernetes to get a li
 
 ```
 $> kubectl get csidrivers.storage.k8s.io
-NAME           AGE
-csi-hostpath   2m
+NAME                  CREATED AT
+hostpath.csi.k8s.io   2019-09-13T09:58:43Z
 ```
 Or get a more detailed view of your registered driver with:
 ```
 $> kubectl describe csidrivers.storage.k8s.io
-Name:         csi-hostpath
-Namespace:
+Name:         hostpath.csi.k8s.io
+Namespace:    
 Labels:       <none>
-Annotations:  <none>
+Annotations:  kubectl.kubernetes.io/last-applied-configuration:
+                {"apiVersion":"storage.k8s.io/v1beta1","kind":"CSIDriver","metadata":{"annotations":{},"name":"hostpath.csi.k8s.io"},"spec":{"podInfoOnMou...
 API Version:  storage.k8s.io/v1beta1
 Kind:         CSIDriver
 Metadata:
-  Creation Timestamp:  2018-10-04T21:15:30Z
-  Generation:          1
-  Resource Version:    390
-  Self Link:           /apis/storage.k8s.io/v1beta1/csidrivers/csi-hostpath
-  UID:                 9f854aa6-c81a-11e8-bdce-000c29e88ff1
+  Creation Timestamp:  2019-09-13T09:58:43Z
+  Resource Version:    341
+  Self Link:           /apis/storage.k8s.io/v1beta1/csidrivers/hostpath.csi.k8s.io
+  UID:                 1860f2a1-85f8-4357-a933-c45e54f0c8e0
 Spec:
-  Attach Required:            true
-  Pod Info On Mount:          false
-Events:                       <none>
+  Attach Required:    true
+  Pod Info On Mount:  true
+  Volume Lifecycle Modes:
+    Persistent
+    Ephemeral
+Events:  <none>
 ```
 
 ## Changes from Alpha to Beta

book/src/ephemeral-local-volumes.md

@@ -4,7 +4,8 @@
 
 Status | Min K8s Version | Max K8s Version 
 --|--|--
-Alpha | 1.15 | - 
+Alpha | 1.15 | 1.15
+Beta | 1.16 | -
 
 ## Overview
 Traditionally, volumes that are backed by CSI drivers can only be used with a `PersistentVolume` and `PersistentVolumeClaim` object combination. This feature supports ephemeral storage use cases and allows CSI volumes to be specified directly in the pod specification.  At runtime, nested inline volumes follow the ephemeral lifecycle of their associated pods where the driver handles all phases of volume operations as pods are created and destroyed.
@@ -38,12 +39,20 @@ Drivers must be modified (or implemented specifically) to support inline ephemer
 - Identity service
 - Node service
 
+Kubernetes 1.16 only allows using a CSI driver for an inline volume if
+its [`CSIDriverInfo`](csi-driver-object.md) object explicitly declares
+that the driver supports that kind of usage in its
+`volumeLifecycleModes` field. This is a safeguard against accidentally
+[using a driver the wrong way](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/20190122-csi-inline-volumes.md#support-for-inline-csi-volumes).
+
 ### Feature gates
-To use inline volume, Kubernetes binaries must start with the `CSIInlineVolume` feature gate enabled:
+To use inline volume, Kubernetes 1.15 binaries must start with the `CSIInlineVolume` feature gate enabled:
 ```
 --feature-gates=CSIInlineVolume=true
 ```
 
+Kubernetes >= 1.16 no longer needs this as the feature is enabled by default.
+
 ### Example implementation
-- [CSI Hostpath driver](https://github.com/kubernetes-csi/csi-driver-host-path) - an example driver that can be configured to support either PVC/PV or inline ephemeral volumes at runtime.
-- [Image populator plugin](https://github.com/kubernetes-csi/csi-driver-image-populator) - an example CSI driver plugin that uses a container image as a volume.
+- [CSI Hostpath driver](https://github.com/kubernetes-csi/csi-driver-host-path) - an example driver that supports both modes and determines the mode on a case-by-case basis (for Kubernetes 1.16) or can be deployed with support for just one of the two modes (for Kubernetes 1.15).
+- [Image populator plugin](https://github.com/kubernetes-csi/csi-driver-image-populator) - an example CSI driver plugin that uses a container image as a volume.