From cd8356339da8286e295a186eee4846ca04620d2a Mon Sep 17 00:00:00 2001
From: Nate Potter <nathaniel.potter@intel.com>
Date: Thu, 15 Oct 2015 14:53:09 +0000
Subject: [PATCH] Add affinity/anti-affinity documentation

This patch documents the affinity and anti-affinity
features in Cinder that allow admins some control
over volume scheduling.

Change-Id: I23404f5974c0e03fca7bdb0af0f8a49644258fed
Closes-Bug: #1342628
---
 doc/user-guide-admin/source/cli.rst           |  1 +
 .../source/cli_cinder_scheduling.rst          | 52 +++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 doc/user-guide-admin/source/cli_cinder_scheduling.rst

diff --git a/doc/user-guide-admin/source/cli.rst b/doc/user-guide-admin/source/cli.rst
index 217073ee46..5e1bbbeeae 100644
--- a/doc/user-guide-admin/source/cli.rst
+++ b/doc/user-guide-admin/source/cli.rst
@@ -19,3 +19,4 @@ OpenStack command-line clients
    cli_admin_manage_environment.rst
    cli_set_quotas.rst
    analyzing-log-files-with-swift-cli.rst
+   cli_cinder_scheduling.rst
diff --git a/doc/user-guide-admin/source/cli_cinder_scheduling.rst b/doc/user-guide-admin/source/cli_cinder_scheduling.rst
new file mode 100644
index 0000000000..d1abdfe7f0
--- /dev/null
+++ b/doc/user-guide-admin/source/cli_cinder_scheduling.rst
@@ -0,0 +1,52 @@
+===============================
+Manage Block Storage scheduling
+===============================
+
+As an administrative user, you have some control over which volume
+back end your volumes reside on. You can specify affinity or
+anti-affinity between two volumes. Affinity between volumes means
+that they are stored on the same back end, whereas anti-affinity
+means that they are stored on different back ends.
+
+For information on how to set up multiple back ends for Cinder,
+refer to the guide for `Configuring multiple-storage back ends
+<http://docs.openstack.org/admin-guide-cloud/blockstorage_multi_backend.html/>`_.
+
+Example Usages
+~~~~~~~~~~~~~~
+
+#. Create new volume on the same back end as Volume_A:
+
+   .. code::
+
+      $ cinder create --hint same_host=Volume_A-UUID SIZE
+
+#. Create new volume on a different back end than Volume_A:
+
+   .. code::
+
+      $ cinder create --hint different_host=Volume_A-UUID SIZE
+
+#. Create new volume on the same back end as Volume_A and Volume_B:
+
+   ..code::
+
+      $ cinder create --hint same_host=Volume_A-UUID --hint same_host=Volume_B-UUID SIZE
+
+   Or:
+
+   ..code::
+
+      $ cinder create --hint same_host="[Volume_A-UUID, Volume_B-UUID]" SIZE
+
+#. Create new volume on a different back end than both Volume_A and Volume_B:
+
+   ..code::
+
+      $ cinder create --hint different_host=Volume_A-UUID --hint different_host=Volume_B-UUID SIZE
+
+   Or:
+
+   ..code::
+
+      $ cinder create --hint different_host="[Volume_A-UUID, Volume_B-UUID]" SIZE