Admin guide documentation for volume multiattach

After giving some love to the multi-attach section it hopefully captures
the main characteristics of the functionality that we usually include
in the Admin Guide, such as volume creation, policies, microversions,
and back end support.

Depends-On: I11f97cf79e0c947b42de69cf8a7f6c1dbdb943a1

Co-Authored-By: Ildiko Vancsa <ildiko.vancsa@gmail.com>
Change-Id: I77bb849e039e1b44964ac0f30d48b5c16ca41b44
This commit is contained in:
Matt Riedemann 2018-02-01 12:17:11 -05:00 committed by Ildiko Vancsa
parent eee1d29e0a
commit cb361631ed
2 changed files with 133 additions and 34 deletions

@ -1,49 +1,147 @@
.. _volume_multiattach:
=============================================
Enable attaching a volume to multiple servers
=============================================
==================================================================
Volume multi-attach: Enable attaching a volume to multiple servers
==================================================================
When configured to allow it and for backends that support it, Cinder
allows a volume to be attached to more than one host/server at a time.
The ability to attach a volume to multiple hosts/servers simultaneously is a
use case desired for active/active or active/standby scenarios.
By default this feature is only enabled for administrators, and is
controlled by policy. If the user is not an admin or the policy file
isn't modified only a single attachment per volume is allowed.
Support was added in both `Cinder`_ and `Nova`_ in the Queens release to volume
multi-attach with read/write (RW) mode.
In addition, the ability to attach a volume to multiple hosts/servers
requires that the volume is of a special type that includes an extra-spec
capability setting of multiattach: True::
.. warning::
It is the responsibility of the user to ensure that a multiattach or
clustered file system is used on the volumes. Otherwise there may be a high
probability of data corruption.
In Cinder the functionality is available from microversion '3.50' or higher.
As a prerequisite `new Attach/Detach APIs were added to Cinder`_ in Ocata to
overcome earlier limitations towards achieving volume multi-attach.
In case you use Cinder together with Nova, compute API calls were switched to
using the new block storage volume attachment APIs in Queens, if the required
block storage API microversion is available.
For more information on using multiattach volumes with the compute service,
refer to the corresponding
`compute admin guide section <https://docs.openstack.org/nova/latest/admin/manage-volumes.html#volume-multi-attach>`_.
How to create a 'multiattach' volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to be able to attach a volume to multiple server instances you need to
have the 'multiattach' flag set to 'True' in the volume details. Please ensure
you have the right role and policy settings before performing the operation.
Currently you can create a multiattach volume in two ways.
.. note::
For information on back ends that provide the functionality see
`Back end support`.
Multiattach volume type
-----------------------
Starting from the Queens release the ability to attach a volume to multiple
hosts/servers requires that the volume is of a special type that includes an
extra-spec capability setting of ``multiattach=<is> True``. You can create the
volume type the following way:
.. code-block:: console
$ cinder type-create multiattach
$ cinder type-key multiattach set multiattach="<is> True"
Now any volume of this type is capable of having multiple simultaneous
attachments. You'll need to ensure you have a backend device that reports
support of the multiattach capability, otherwise scheduling will fail on
create.
At this point Cinder will no longer check in-use status when creating/updating
attachments.
.. note::
This feature is only supported when using the new attachment API's,
attachment-create, attachment-update etc.
Creating a new volume type is an admin-only operation by default, you can
change the settings in the 'policy.json' configuration file if needed.
In addition, it's possible to retype a volume to be multiattach capable.
Currently however we do NOT allow retyping a volume to multiattach:True or
multiattach:False if it's status is not ``avaialable``. This is because some
consumers/hypervisors need to make special considerations at attach-time for
multiattach volumes (ie disable caching) and there's no mechanism currently to
go back to ``in-use`` volumes and update them. While going from
``multiattach:True`` --> ``multiattach:False`` isn't as problematic, it is
error prone when it comes to special cases like shelve, migrate etc. The bottom
line is it's *safer* to just avoid changing this setting on ``in-use`` volumes.
To create the volume you need to use the volume type you created earlier, like
this:
Finally, note that Cinder (nor its backends) does not do anything in terms of file
systems or control of the volumes. In other words, it's up to the user to
ensure that a multiattach or clustered file system is used on the volumes.
Otherwise there may be a high probability of data corruption.
.. code-block:: console
$ cinder create <volume_size> --name <volume_name> --volume-type <volume_type_uuid>
In addition, it is possible to retype a volume to be (or not to be) multiattach
capable. Currently however we only allow retyping a volume if its status is
``available``.
The reasoning behind the limitation is that some consumers/hypervisors need to
make special considerations at attach-time for multiattach volumes (like
disable caching) and there's no mechanism currently to update a currently
attached volume in a safe way while keeping it attached the whole time.
Multiattach flag - DEPRECATED
-----------------------------
Starting from the Queens release using the old way of specifying multiattach
with the flag is DEPRECATED:
.. code-block:: console
$ cinder create <volume_size> --name <volume_name> --allow-multiattch
RO / RW caveats (the secondary RW attachment issue)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, secondary volume attachments are made in read/write mode
which can be problematic, especially for operations like volume migration.
There might be improvements to provide support to specify the attach-mode for
the secondary attachments, for the latest information please take a look into
`Cinder's specs list`_ for the current release.
Back end support
~~~~~~~~~~~~~~~~
In order to have the feature available, multi-attach needs to be supported by
the chosen back end which is indicated through capabilities in the
corresponding volume driver.
The reference implementation is available on LVM in the Queens release. You can
check the `Driver Support Matrix`_ for further information on which back end
provides the functionality.
Policy rules
~~~~~~~~~~~~
You can control the availability of volume multi-attach through policies. We
describe the default values in this documentation, you need to modify the
'policy.json' configuration file if you would like to changes these settings.
Multiattach policy
------------------
The general policy rule to allow the creation or retyping of multiattach
volumes is named ``volume:multiattach``.
The default setting of this policy is ``rule:admin_or_owner``.
Multiattach policy for bootable volumes
---------------------------------------
This is a policy to disallow the ability to create multiple attachments on a
volume that is marked as bootable with the name
``volume:multiattach_bootable_volume``.
This is an attachment policy with a default setting of ``rule:admin_or_owner``.
Known issues and limitations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Retyping an in-use volume from a multiattach-capable type to a
non-multiattach-capable type, or vice-versa, is not supported.
- It is not recommended to retype an in-use multiattach volume if that volume
has more than one active read/write attachment.
.. _`Cinder`: https://specs.openstack.org/openstack/cinder-specs/specs/queens/enable-multiattach.html
.. _`Nova`: https://specs.openstack.org/openstack/nova-specs/specs/queens/approved/cinder-volume-multi-attach.html
.. _`new Attach/Detach APIs were added to Cinder`: http://specs.openstack.org/openstack/cinder-specs/specs/ocata/add-new-attach-apis.html
.. _`Cinder's specs list`: https://specs.openstack.org/openstack/cinder-specs/index.html
.. _`Driver Support Matrix`: https://wiki.openstack.org/wiki/CinderSupportMatrix

@ -56,6 +56,7 @@ extensions = ['sphinx.ext.autodoc',
'sphinx.ext.coverage',
'sphinx.ext.ifconfig',
'sphinx.ext.graphviz',
'sphinx.ext.todo',
'openstackdocstheme',
'stevedore.sphinxext',
'oslo_config.sphinxconfiggen',