Merge pull request #121 from jsafrane/csidriver-beta

Update CSIDriver and CSINodeInfo features to beta

book/src/SUMMARY.md

@@ -9,7 +9,7 @@
         - [node-driver-registrar](node-driver-registrar.md)
         - [cluster-driver-registrar](cluster-driver-registrar.md)
         - [livenessprobe](livenessprobe.md)
-    - [CSI CRDs](csi-crds.md)
+    - [CSI objects](csi-objects.md)
       - [CSIDriver Object](csi-driver-object.md)
       - [CSINodeInfo Object](csi-node-info-object.md)
     - [Features](features.md)

book/src/csi-driver-object.md

@@ -2,7 +2,8 @@
 
 ## Status
 
-Alpha
+* Kubernetes 1.12 - 1.13: Alpha
+* Kubernetes 1.14: Beta
 
 ## What is the CSIDriver object?
 
@@ -15,16 +16,16 @@ The `CSIDriver` Kubernetes API object serves two purposes:
 
 ## What fields does the `CSIDriver` object have?
 
-Here is an example of a v1alpha1 `CSIDriver` object:
+Here is an example of a v1beta1 `CSIDriver` object:
 
 ```YAML
-apiVersion: csi.storage.k8s.io/v1alpha1
+apiVersion: storage.k8s.io/v1beta1
 kind: CSIDriver
 metadata:
   name: mycsidriver.example.com
 spec:
   attachRequired: true
-  podInfoOnMountVersion: v1
+  podInfoOnMount: true
 ```
 
 There are three important fields:
@@ -36,60 +37,63 @@ There are three important fields:
   * If a `CSIDriver` object does not exist for a given CSI Driver, the default is `true` -- meaning attach will be called.
   * If a `CSIDriver` object exists for a given CSI Driver, but this field is not specified, it also defaults to `true` -- meaning attach will be called.
   * For more information see [Skip Attach](skip-attach.md).
-* `podInfoOnMountVersion`
+* `podInfoOnMount`
   * Indicates this CSI volume driver requires additional pod information (like pod name, pod UID, etc.) during mount operations.
-  * If value is not specified, pod information will not be passed on mount.
-  * If value is set to a valid version, Kubelet will pass pod information as `volume_context` in CSI `NodePublishVolume` calls.
-  * Supported versions:
-    * Version "v1" will pass the following additional fields in `volume_context`:
-	  * `"csi.storage.k8s.io/pod.name": pod.Name`
-	  * `csi.storage.k8s.io/pod.namespace": pod.Namespace`
-	  * `csi.storage.k8s.io/pod.uid": string(pod.UID)`
+  * If value is not specified or `false`, pod information will not be passed on mount.
+  * If value is set to `true`, Kubelet will pass pod information as `volume_context` in CSI `NodePublishVolume` calls:
+    * `"csi.storage.k8s.io/pod.name": pod.Name`
+    * `"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).
 
 ## What creates the CSIDriver object?
 
-CSI drivers do not need to create the `CSIDriver` object directly. Instead they may use the [cluster-driver-registrar](cluster-driver-registrar.md) sidecar container (customizing it as needed with startup parameters) -- when deployed with a CSI driver it automatically creates a `CSIDriver` CR representing the driver.
-
-### Enabling CSIDriver
-
-The `CSIDriver` object is available as alpha starting with Kubernetes v1.12. Because it is an alpha feature, it is disabled by default.
-It is planned to be moved to beta in Kubernetes v1.14 and enabled by default.
-
-To enable the use of `CSIDriver` on Kubernetes, do the following:
-
-1) Ensure the feature gate is enabled via the following Kubernetes feature flag: `--feature-gates=CSIDriverRegistry=true`
-2) Either ensure the `CSIDriver` CRD is automatically installed via the [Kubernetes Storage CRD addon](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/storage-crds) OR manually install the `CSIDriver` CRD on the Kubernetes cluster with the following command:
-```
-$> kubectl create -f https://raw.githubusercontent.com/kubernetes/csi-api/master/pkg/crd/manifests/csidriver.yaml
-```
+CSI drivers do not need to create the `CSIDriver` object directly. Instead they may use the [cluster-driver-registrar](cluster-driver-registrar.md) sidecar container (customizing it as needed with startup parameters). When deployed with a CSI driver, this sidecar will automatically creates a `CSIDriver` object to represent the driver.
 
 ### Listing registered CSI drivers
-Using the `CSIDriver` CRD, it is now possible to query Kubernetes to get a list of registered drivers running in the cluster as shown below:
+Using the `CSIDriver` object, it is now possible to query Kubernetes to get a list of registered drivers running in the cluster as shown below:
 
 ```
-$> kubectl get csidrivers.csi.storage.k8s.io
+$> kubectl get csidrivers.storage.k8s.io
 NAME           AGE
 csi-hostpath   2m
 ```
 Or get a more detailed view of your registered driver with:
 ```
-$> kubectl describe csidrivers.csi.storage.k8s.io
+$> kubectl describe csidrivers.storage.k8s.io
 Name:         csi-hostpath
 Namespace:
 Labels:       <none>
 Annotations:  <none>
-API Version:  csi.storage.k8s.io/v1alpha1
+API Version:  storage.k8s.io/v1beta1
 Kind:         CSIDriver
 Metadata:
   Creation Timestamp:  2018-10-04T21:15:30Z
   Generation:          1
   Resource Version:    390
-  Self Link:           /apis/csi.storage.k8s.io/v1alpha1/csidrivers/csi-hostpath
+  Self Link:           /apis/storage.k8s.io/v1beta1/csidrivers/csi-hostpath
   UID:                 9f854aa6-c81a-11e8-bdce-000c29e88ff1
 Spec:
   Attach Required:            true
-  Pod Info On Mount Version:
+  Pod Info On Mount:          false
 Events:                       <none>
 ```
 
+## Changes from Alpha to Beta
+### CRD to Built in Type
+During alpha development, the `CSIDriver` object was also defined as a [Custom Resource Definition](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#create-a-customresourcedefinition) (CRD). As part of the promotion to beta the object has been moved to the built-in Kubernetes API.
+
+In the move from alpha to beta, the API Group for this object changed from `csi.storage.k8s.io/v1alpha1` to `storage.k8s.io/v1beta1`.
+
+There is no automatic update of existing CRDs and their CRs during Kubernetes update to the new build-in type.
+
+### Enabling CSIDriver on Kubernetes
+In Kubernetes v1.12 and v1.13, because the feature was alpha, it was disabled by default. To enable the use of `CSIDriver` on these versions, do the following:
+
+1. Ensure the feature gate is enabled via the following Kubernetes feature flag: `--feature-gates=CSIDriverRegistry=true`
+2. Either ensure the `CSIDriver` CRD is automatically installed via the [Kubernetes Storage CRD addon](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/storage-crds) OR manually install the `CSIDriver` CRD on the Kubernetes cluster with the following command:
+
+```
+$> kubectl create -f https://raw.githubusercontent.com/kubernetes/csi-api/master/pkg/crd/manifests/csidriver.yaml
+```
+Kubernetes v1.14+, uses the same Kubernetes feature flag, but because the feature is beta, it is enabled by default. And since the API type (as of beta) is built in to the Kubernetes API, installation of the CRD is no longer required.

book/src/csi-node-info-object.md

@@ -2,11 +2,12 @@
 
 ## Status
 
-Alpha
+* Kubernetes 1.12 - 1.13: Alpha
+* Kubernetes 1.14: Beta
 
 ## What is the CSINodeInfo object?
 
-CSI drivers generate node specific information. Instead of storing this in the Kubernetes `Node` API Object, a new CSI specific Kubernetes CRD was created, the `CSINodeInfo` CRD.
+CSI drivers generate node specific information. Instead of storing this in the Kubernetes `Node` API Object, a new CSI specific Kubernetes `CSINodeInfo` object was created.
 
 It serves the following purposes:
 
@@ -23,7 +24,7 @@ It serves the following purposes:
 Here is an example of a v1alpha1 `CSINodeInfo` object:
 
 ```YAML
-apiVersion: csi.storage.k8s.io/v1alpha1
+apiVersion: storage.k8s.io/v1beta1
 kind: CSINodeInfo
 metadata:
   name: node1
@@ -48,16 +49,23 @@ Where the fields mean:
 
 ## What creates the CSINodeInfo object?
 
-CSI drivers do not need to create the `CSINodeInfo` object directly. As long as they use the [node-driver-registrar](node-driver-registrar.md) sidecar container, the kubelet will automatically populate the `CSINodeInfo` object for the CSI driver as part of kubelet plugin registration.
+CSI drivers do not need to create the `CSINodeInfo` object directly. Instead they should use the [node-driver-registrar](node-driver-registrar.md) sidecar container. This sidecar container will interact with kubelet via the kubelet plugin registration mechanism to automatically populate the `CSINodeInfo` object on behalf of the the CSI driver.
 
-### Enabling CSINodeInfo
+## Changes from Alpha to Beta
+### CRD to Built in Type
+During alpha development, the `CSINodeInfo` object was also defined as a [Custom Resource Definition](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#create-a-customresourcedefinition) (CRD). As part of the promotion to beta the object has been moved to the built-in Kubernetes API.
 
-The `CSINodeInfo` object is available as alpha starting with Kubernetes v1.12. Because it is an alpha feature, it is disabled by default.
+In the move from alpha to beta, the API Group for this object changed from `csi.storage.k8s.io/v1alpha1` to `storage.k8s.io/v1beta1`.
 
-To enable use of `CSINodeInfo` on Kubernetes, do the following:
+There is no automatic update of existing CRDs and their CRs during Kubernetes update to the new build-in type.
+
+### Enabling CSINodeInfo on Kubernetes
+In Kubernetes v1.12 and v1.13, because the feature was alpha, it was disabled by default. To enable the use of `CSIDriver` on these versions, do the following:
+
+1. Ensure the feature gate is enabled with `--feature-gates=CSINodeInfo=true`
+2. Either ensure the `CSIDriver` CRD is automatically installed via the [Kubernetes Storage CRD addon](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/storage-crds) OR manually install the `CSINodeInfo` CRD on the Kubernetes cluster with the following command:
 
-1) Ensure the feature gate is enabled with `--feature-gates=CSINodeInfo=true`
-2) Either ensure the `CSIDriver` CRD is automatically installed via the [Kubernetes Storage CRD addon](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/storage-crds) OR manually install the `CSINodeInfo` CRD on the Kubernetes cluster with the following command:
 ```
 $> kubectl create -f https://raw.githubusercontent.com/kubernetes/csi-api/master/pkg/crd/manifests/csinodeinfo.yaml
 ```
+Kubernetes v1.14+, uses the same Kubernetes feature flag, but because the feature is beta, it is enabled by default. And since the API type (as of beta) is built in to the Kubernetes API, installation of the CRD is no longer required.

book/src/csi-objects.md

@@ -0,0 +1,12 @@
+# CSI objects
+
+**Status:** Beta
+
+The Kubernetes API contains the following CSI specific objects:
+
+* [CSIDriver Object](csi-driver-object.md)
+* [CSINodeInfo Object](csi-node-info-object.md)
+
+Both are part of `storage.k8s.io/v1beta1` API group.
+
+The schema definition for the objects can be found here: https://github.com/kubernetes/kubernetes/blob/master/pkg/apis/storage/types.go

book/src/introduction.md

@@ -51,7 +51,7 @@ It aims to reduce boilerplate code and  simplify the overall process for CSI Dri
 This "Recommended Mechanism" makes use of the following components:
 
 * Kubernetes CSI [Sidecar Containers](sidecar-containers.md)
-* Kubernetes CSI [CRDs](csi-crds.md)
+* Kubernetes CSI [objects](csi-objects.md)
 * CSI [Driver Testing](testing-drivers.md) tools
 
 To implement a CSI driver using this mechanism, a CSI driver developer should:

book/src/pod-info.md

@@ -1,6 +1,8 @@
 # Pod Info on Mount
 
-**Status:** Alpha
+**Status:** Beta
+
+The "Pod Info on Mount" feature was introduced as alpha in Kubernetes v1.12. It was promoted to beta in Kubernetes 1.13.
 
 # Problem
 
@@ -12,26 +14,36 @@ This can be problematic because some CSI drivers require information about the w
 
 The [CSIDriver Object](csi-driver-object.md) enables CSI Drivers to specify how Kubernetes should interact with it.
 
-Specifically the `podInfoOnMountVersion` field instructs Kubernetes that the CSI driver requires additional pod information (like podName, podUID, etc.) during mount operations.
+Specifically the `podInfoOnMount` field instructs Kubernetes that the CSI driver requires additional pod information (like podName, podUID, etc.) during mount operations.
 
-For example, the existence of the following object would cause Kubernetes to add pod information at mount time to the `NodePublishVolumeRequest.volume_context` map.
+For example, the existence of the following object would cause Kubernetes to add pod information at mount time to the `NodePublishVolumeRequest.publish_context` map.
 
 ```
-apiVersion: csi.storage.k8s.io/v1alpha1
+apiVersion: storage.k8s.io/v1beta1
 kind: CSIDriver
 metadata:
   name: testcsidriver.example.com
 spec:
-  podInfoOnMountVersion: v1
+  podInfoOnMount: true
 ```
 
-There is only one `podInfoOnMountVersion` version currently supported: `v1`.
+If the `podInfoOnMount` field is set to `true`, during mount, Kubelet will add the following key/values to the `publish_context` field in the CSI `NodePublishVolumeRequest`:
 
-The value `v1` for `podInfoOnMountVersion` will result in the following key/values being added to `publish_context`:
 
 * `csi.storage.k8s.io/pod.name: {pod.Name}`
 * `csi.storage.k8s.io/pod.namespace: {pod.Namespace}`
 * `csi.storage.k8s.io/pod.uid: {pod.UID}`
 
-
 The easiest way to use this feature is to deploy the [cluster-driver-registrar](cluster-driver-registrar.md) sidecar container. Once the flags to this container are configured correctly, it will automatically create a [CSIDriver Object](csi-driver-object.md) when it starts with the correct fields set.
+
+## Alpha Functionality
+In alpha, this feature was enabled by setting the `podInfoOnMountVersion` field in the `CSIDriver` Object CRD to to `v1`.
+
+```
+apiVersion: csi.storage.k8s.io/v1alpha1
+kind: CSIDriver
+metadata:
+  name: testcsidriver.example.com
+spec:
+  podInfoOnMountVersion: v1
+```

book/src/skip-attach.md

@@ -1,6 +1,8 @@
 # Skip Kubernetes Attach and Detach
 
-**Status:** Alpha
+**Status:** Beta
+
+The "Skip Kubernetes Attach and Detach" feature was introduced as alpha in Kubernetes v1.12. It was promoted to beta in Kubernetes 1.13.
 
 # Problem
 
@@ -19,7 +21,7 @@ Specifically the `attachRequired` field instructs Kubernetes to skip any attach
 For example, the existence of the following object would cause Kubernetes to skip attach operations for all CSI Driver `testcsidriver.example.com` volumes.
 
 ```
-apiVersion: csi.storage.k8s.io/v1alpha1
+apiVersion: storage.k8s.io/v1beta1
 kind: CSIDriver
 metadata:
   name: testcsidriver.example.com
@@ -28,3 +30,13 @@ spec:
 ```
 
 The easiest way to use this feature is to deploy the [cluster-driver-registrar](cluster-driver-registrar.md) sidecar container. Once the flags to this container are configured correctly, it will automatically create a [CSIDriver Object](csi-driver-object.md) when it starts with the correct fields set.
+
+## Alpha Functionality
+In alpha, this feature was enabled via the [CSIDriver Object](csi-driver-object.md) CRD.
+
+```
+apiVersion: csi.storage.k8s.io/v1alpha1
+kind: CSIDriver
+metadata:
+....
+```