From c2bf624c9b71abbb10c5a8dc6bd4baa69ab2a3dc Mon Sep 17 00:00:00 2001
From: Kristi Nikolla <knikolla@bu.edu>
Date: Mon, 13 Feb 2017 11:33:34 -0500
Subject: [PATCH] Volume backends docs

This add a page of documentation on how to setup volume backends
for mix and match.

Change-Id: Ie784635591cae71c2cf1c4264e47af6a7443361f
---
 doc/source/index.rst   |  1 +
 doc/source/volumes.rst | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100644 doc/source/volumes.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index b3abcde..6f11e98 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -15,6 +15,7 @@ Contents:
    architecture
    installation
    identity
+   volumes
    contributing
 
 Indices and tables
diff --git a/doc/source/volumes.rst b/doc/source/volumes.rst
new file mode 100644
index 0000000..a22d61a
--- /dev/null
+++ b/doc/source/volumes.rst
@@ -0,0 +1,40 @@
+=================
+Volume Federation
+=================
+
+RBD
+===
+When using RBD (Ceph) as the driver for Cinder, volumes are stored in a Ceph
+pool. Access to the pool is granted through a CephX authentication key and
+this key is shared among all Nova compute nodes.
+
+Please follow Ceph's documentation_ on setting up OpenStack with RBD.
+
+The ``libvirt`` secret key should match the credentials for accessing the pool
+in both deployments. So if you have two OpenStack deployments and they
+respectively access the RBD pool through secret keys
+``bab2fea0-a834-48ad-8b27-6b7ce6aeab13`` and
+``dfb36a63-484c-48b2-8a47-4de8915dacfb`` that map to CephX authentications,
+then compute nodes in both deployments should have both of these secret keys
+configured.
+
+.. NOTE::
+
+   Due to `bug 1635008`_ it is not possible to use RBD for ephemeral storage
+   and also for federating volumes in RBD prior to the Ocata release. This is
+   because Nova will trust the RBD information that it uses to store ephemeral
+   disks over the information coming from Cinder, which should be the correct
+   information.
+
+
+.. _`bug 1635008`: https://bugs.launchpad.net/nova/+bug/1635008
+.. _documentation: http://docs.ceph.com/docs/master/rbd/rbd-openstack/
+
+
+LVM
+===
+LVM uses an iSCSI server to share the Cinder volume with Nova compute nodes.
+The credentials to access each volume are randomly generated by Cinder and
+passed to Nova during volume attachment. No special setup needs to be done
+in this scenario, other than to ensure compute nodes are able to access the
+iSCSI server through the network.