Add admin guide doc on volume multiattach support

This is the companion doc to the admin guide docs
in cinder:

I77bb849e039e1b44964ac0f30d48b5c16ca41b44

Change-Id: I11f97cf79e0c947b42de69cf8a7f6c1dbdb943a1
(cherry picked from commit 4d226e5f0ae390300e7d0013d3239e0da976e8aa)

1 files changed, 64 insertions, 0 deletions

diff --git a/doc/source/admin/manage-volumes.rst b/doc/source/admin/manage-volumes.rst
index 5b6f156983..2c8374a7f4 100644
--- a/doc/source/admin/manage-volumes.rst
+++ b/doc/source/admin/manage-volumes.rst
@@ -11,3 +11,67 @@ are of primary interest.
 
 Refer to the `block storage service CLI guide on managing volumes
 <https://docs.openstack.org/cinder/latest/cli/cli-manage-volumes.html>`_.
+
+
+Volume multi-attach
+-------------------
+
+Nova `added support for multiattach volumes`_ in the 17.0.0 Queens release.
+
+This document covers the nova-specific aspects of this feature. Refer
+to the `block storage admin guide`_ for more details about creating
+multiattach-capable volumes.
+
+Boot from volume and attaching a volume to a server that is not
+SHELVED_OFFLOADED is supported. Ultimately the ability to perform
+these actions depends on the compute host and hypervisor driver that
+is being used.
+
+Requirements
+~~~~~~~~~~~~
+
+* The minimum required compute API microversion for attaching a
+  multiattach-capable volume to more than one server is `2.60`_.
+* Cinder 12.0.0 (Queens) or newer is required.
+* The ``nova-compute`` service must be running at least Queens release level
+  code (17.0.0) and the hypervisor driver must support attaching block storage
+  devices to more than one guest. Refer to the `feature support matrix`_ for
+  details on which compute drivers support volume multiattach.
+* When using the libvirt compute driver, the following native package versions
+  determine multiattach support:
+
+  * libvirt must be greater than or equal to 3.10, or
+  * qemu must be less than 2.10
+
+* Swapping an *in-use* multiattach volume is not supported (this is actually
+  controlled via the block storage volume retype API).
+
+Known issues
+~~~~~~~~~~~~
+
+* Creating multiple servers in a single request with a multiattach-capable
+  volume as the root disk is not yet supported: https://bugs.launchpad.net/nova/+bug/1747985
+* Subsequent attachments to the same volume are all attached in *read/write*
+  mode by default in the block storage service. A future change either in nova
+  or cinder may address this so that subsequent attachments are made in
+  *read-only* mode, or such that the mode can be specified by the user when
+  attaching the volume to the server.
+
+Testing
+~~~~~~~
+
+Continuous integration testing of the volume multiattach feature is done
+via the ``nova-multiattach`` job, defined in the `nova repository`_.
+
+The tests are defined in the `tempest repository`_.
+
+The CI job is setup to run with the **libvirt** compute driver and the **lvm**
+volume back end. It purposefully does not use the Pike Ubuntu Cloud Archive
+package mirror so that it gets qemu<2.10.
+
+.. _added support for multiattach volumes: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/multi-attach-volume.html
+.. _block storage admin guide: https://docs.openstack.org/cinder/latest/admin/blockstorage-volume-multiattach.html
+.. _2.60: https://docs.openstack.org/nova/latest/reference/api-microversion-history.html#maximum-in-queens
+.. _feature support matrix: https://docs.openstack.org/nova/latest/user/support-matrix.html#operation_multiattach_volume
+.. _nova repository: http://git.openstack.org/cgit/openstack/nova/tree/playbooks/legacy/nova-multiattach/run.yaml
+.. _tempest repository: http://codesearch.openstack.org/?q=CONF.compute_feature_enabled.volume_multiattach&i=nope&files=&repos=tempest