Moving CSI to Out of Tree section; linking to out of tree plugin FAQ (#7564)

docs/concepts/storage/volumes.md

@@ -215,38 +215,6 @@ keyed with `log_level`.
 receive ConfigMap updates.
 {: .note}
 
-### 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 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.
@@ -990,16 +958,50 @@ several media types.
 ## Out-of-Tree Volume Plugins
 In addition to the previously listed volume types, storage vendors may create
 custom plugins without adding it to the Kubernetes repository. This can be
-achieved by using the `FlexVolume` plugin.
+achieved by using either the `CSI` plugin or the `FlexVolume` plugin.
 
+For storage vendors looking to create an out-of-tree volume plugin, [please refer to this FAQ](https://github.com/kubernetes/community/blob/master/sig-storage/volume-plugin-faq.md) for choosing between the plugin options.
+
+### 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 can use to expose arbitrary storage systems
+to their container workloads.
+Please read
+[CSI design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/container-storage-interface.md) for further information.
+
+<!-- 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 an alpha feature in Kubernetes v1.9 and requires a
+cluster administrator to enable it. To enable CSI persistent volume support, the
+cluster administrator adds `CSIPersistentVolume=true` to the `--feature-gates` flag
+for apiserver, controller-manager, and kubelet.
+
+The following fields are available to storage administrators to configure a CSI
+persistent volume:
+
+- `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 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.
+
+### FlexVolume
 `FlexVolume` enables users to mount vendor volumes into a pod. The vendor plugin
 is implemented using a driver, an executable supporting a list of volume commands
 defined by the `FlexVolume` API. Drivers must be installed in a pre-defined
-volume plugin path on each node.
+volume plugin path on each node. Pods interact with FlexVolume drivers through the `flexVolume` in-tree plugin.
 
 More details can be found [here](https://github.com/kubernetes/community/blob/master/contributors/devel/flexvolume.md).
 
-
 ## Mount propagation
 
 **Note:** Mount propagation is an alpha feature in Kubernetes 1.8 and may be