Update NEWS and docs to document access switch

* Update NEWS file
* Update man page
* Update install.rst
Signed-off-by: Santi Raffa <rsanti@google.com>
Signed-off-by: Thomas Thrainer <thomasth@google.com>
Reviewed-by: Thomas Thrainer <thomasth@google.com>

NEWS

@@ -7,6 +7,11 @@ Version 2.10.0 alpha1
 
 *(unreleased)*
 
+New features
+~~~~~~~~~~~~
+- KVM hypervisors can now access RBD storage directly without having to
+  go through a block device.
+
 Incompatible/important changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/install.rst

@@ -367,6 +367,31 @@ above. We recommend using the latest version of ``ceph-common``.
 
       $ apt-get install ceph-common
 
+KVM userspace access
+~~~~~~~~~~~~~~~~~~~~
+
+If your cluster uses a sufficiently new version of KVM (you will need at
+least QEMU 0.14 with RBD support compiled in), you can take advantage of
+KVM's native support for ceph in order to have better performance and
+avoid potential deadlocks_ in low memory scenarios.
+
+.. _deadlocks: http://tracker.ceph.com/issues/3076
+
+To initialize a cluster with support for this feature, use a command
+such as::
+
+  $ gnt-cluster init \
+      --enabled-disk-templates rbd \
+      --ipolicy-disk-templates rbd \
+      --enabled-hypervisors=kvm \
+      -D rbd:access=userspace
+
+(You may want to enable more templates than just ``rbd``.)
+
+You can also change this setting on a live cluster by giving the same
+switches to ``gnt-cluster modify``, or change those settings at the node
+group level with ``gnt-group modify``.
+
 Configuration file
 ~~~~~~~~~~~~~~~~~~
 

man/gnt-cluster.rst

@@ -469,6 +469,21 @@ pool
     When a new RADOS cluster is deployed, the default pool to put rbd
     volumes (Images in RADOS terminology) is 'rbd'.
 
+access
+    If 'userspace', instances will access their disks directly without
+    going through a block device, avoiding expensive context switches
+    with kernel space and the potential for deadlocks_ in low memory
+    scenarios.
+
+    The default value is 'kernelspace' and it disables this behaviour.
+    This setting may only be changed to 'userspace' if all instance
+    disks in the affected group or cluster can be accessed in userspace.
+
+    Attempts to use this feature without rbd support compiled in KVM
+    result in a "no such file or directory" error messages.
+
+.. _deadlocks: http://tracker.ceph.com/issues/3076
+
 The option ``--maintain-node-health`` allows one to enable/disable
 automatic maintenance actions on nodes. Currently these include
 automatic shutdown of instances and deactivation of DRBD devices on