Documentation for CSIPersistentVolume

Author: tengqm

docs/concepts/storage/volumes.md

@@ -69,6 +69,7 @@ Kubernetes supports several types of Volumes:
    * `azureDisk`
    * `azureFile`
    * `cephfs`
+   * `csi`
    * `downwardAPI`
    * `emptyDir`
    * `fc` (fibre channel)
@@ -170,6 +171,38 @@ writers simultaneously.
 
 See the [CephFS example](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/volumes/cephfs/) for more details.
 
+### csi
+
+CSI stands for [Container Storage Interface](https://github.com/container-storage-interface/spec/blob/master/spec.md),
+a specification attempting to establish an industry standard interface that
+Container Orchestration Systems (COs) can use to expose arbitrary storage systems
+to their container workloads.
+For more information about the details, please check the
+[design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/container-storage-interface.md).
+
+<!-- TODO: add link to the kubernetes extension section -->
+The `csi` volume type is an in-tree CSI volume plugin for Pods to interact
+with external CSI volume drivers running on the same node.
+After having deployed a CSI compatible volume driver, users can use `csi` as the
+volume type to mount the storage provided by the driver.
+
+CSI persistent volume support is introduced in Kubernetes v1.9 as an alpha feature
+which has to be explicitly enabled by the cluster administrator. In other words,
+the cluster administrator needs to add "`CSIPersistentVolume=true`" to the
+"`--feature-gates=`" flag for the apiserver, the controller-manager and the kubelet
+components.
+
+A CSI persistent volume has the following fields for users to specify:
+
+- `driver`: A string value that specifies the name of the volume driver to use.
+  It has to be less than 63 characters and starts with a character. The driver
+  name can have '`.`', '`-`', '`_`' or digits in it.
+- `volumeHandle`: A string value that uniquely identify the volume name returned
+  from the CSI volume plugin's `CreateVolume` call. The volume handle is then
+  used in all subsequent calls to the the volume driver for referencing the volume.
+- `readOnly`: An optional boolean value indicating whether the volume is to be
+  published as read only. Default is false.
+
 ### downwardAPI
 
 A `downwardAPI` volume is used to make downward API data available to applications.