diff --git a/docs/concepts/cluster-administration/cloud-providers.md b/docs/concepts/cluster-administration/cloud-providers.md
index 354ece59d8ca8..38ebe143714ce 100644
--- a/docs/concepts/cluster-administration/cloud-providers.md
+++ b/docs/concepts/cluster-administration/cloud-providers.md
@@ -88,6 +88,37 @@ subnet-id=6937f8fa-858d-4bc9-a3a5-18d2c957166a
 
 ####  Load Balancer
 * `subnet-id`: Used to specify the id of the subnet you want to create your loadbalancer on. Can be found at Network > Networks. Click on the respective network to get its subnets.
+
+### Optional configuration
+
+#### Block Storage
+
+Kubernetes uses the OpenStack service catalog to locate services it knows how to
+use including Cinder Block Storage. The cloud provider configuration does
+however include an additional option for influencing the way the block storage
+API is used:
+
+* `bs-version`: Refers to the version of the block storage API to use. Valid
+  values are `v1`, `v2`, `v3` and `auto`. The `auto` value is the default and
+  will use the newest version of the block storage API supported by the
+  underlying OpenStack cloud.
+
+If deploying Kubernetes versions <= 1.8 on an OpenStack deployment that uses
+paths rather than ports to differentiate between endpoints it may be necessary
+to explicitly set the `bs-version` parameter. A path based endpoint is of the
+form `http://foo.bar/volume` while a port based endpoint is of the form
+`http://foo.bar:xxx`.
+
+In environments that use path based endpoints and Kubernetes is using the older
+auto-detection logic a `BS API version autodetection failed.` error will be
+returned on attempting volume detachment. To workaround this issue it is
+possible to force the use of Cinder API version 2 by adding this to the cloud
+provider configuration:
+
+```yaml
+[BlockStorage]
+bs-version=v2
+```
 {% endcapture %}
 
 {% include templates/concept.md %}