From 70040856aaff069fabab84b64fb0c2858bdb1b7d Mon Sep 17 00:00:00 2001 From: Lee Yarwood Date: Wed, 15 Sep 2021 10:20:50 +0100 Subject: [PATCH] docs: Add nova-volume volume_attachment refresh admin workflow This adds some basic documentation for the above command and also includes some very generic osc commands to use when checking volume attachments. Blueprint: nova-manage-refresh-connection-info Change-Id: Ib3d680654fe0809c9e8341dffd3a63ab02945a38 --- doc/source/admin/manage-volumes.rst | 143 ++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) diff --git a/doc/source/admin/manage-volumes.rst b/doc/source/admin/manage-volumes.rst index 84377dd88f92..a9d705a47aab 100644 --- a/doc/source/admin/manage-volumes.rst +++ b/doc/source/admin/manage-volumes.rst @@ -71,3 +71,146 @@ tests themselves, are defined in the `tempest repository`_. .. _added support for multiattach volumes: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/multi-attach-volume.html .. _recorded overview and demo: https://www.youtube.com/watch?v=hZg6wqxdEHk .. _tempest repository: http://codesearch.openstack.org/?q=CONF.compute_feature_enabled.volume_multiattach&i=nope&files=&repos=tempest + +Managing volume attachments +--------------------------- + +During the lifecycle of an instance admins may need to check various aspects of +how a given volume is mapped both to an instance and the underlying compute +hosting the instance. This could even include refreshing different elements of +the attachment to ensure the latest configuration changes within the +environment have been applied. + +Checking an existing attachment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Existing volume attachments can be checked using the following +:python-openstackclient-doc:`OpenStack Client commands `: + +List all volume attachments for a given instance: + +.. code-block:: shell + + $ openstack server volume list 216f9481-4c9d-4530-b865-51cedfa4b8e7 + +--------------------------------------+----------+--------------------------------------+--------------------------------------+ + | ID | Device | Server ID | Volume ID | + +--------------------------------------+----------+--------------------------------------+--------------------------------------+ + | 8b9b3491-f083-4485-8374-258372f3db35 | /dev/vdb | 216f9481-4c9d-4530-b865-51cedfa4b8e7 | 8b9b3491-f083-4485-8374-258372f3db35 | + +--------------------------------------+----------+--------------------------------------+--------------------------------------+ + +List all volume attachments for a given instance with the Cinder volume +attachment and Block Device Mapping UUIDs also listed with microversion >=2.89: + +.. code-block:: shell + + $ openstack --os-compute-api-version 2.89 server volume list 216f9481-4c9d-4530-b865-51cedfa4b8e7 + +----------+--------------------------------------+--------------------------------------+------+------------------------+--------------------------------------+--------------------------------------+ + | Device | Server ID | Volume ID | Tag | Delete On Termination? | Attachment ID | BlockDeviceMapping UUID | + +----------+--------------------------------------+--------------------------------------+------+------------------------+--------------------------------------+--------------------------------------+ + | /dev/vdb | 216f9481-4c9d-4530-b865-51cedfa4b8e7 | 8b9b3491-f083-4485-8374-258372f3db35 | None | False | d338fb38-cfd5-461f-8753-145dcbdb6c78 | 4e957e6d-52f2-44da-8cf8-3f1ab755e26d | + +----------+--------------------------------------+--------------------------------------+------+------------------------+--------------------------------------+--------------------------------------+ + +List all Cinder volume attachments for a given volume from microversion >= +3.27: + +.. code-block:: shell + + $ openstack --os-volume-api-version 3.27 volume attachment list --volume-id 8b9b3491-f083-4485-8374-258372f3db35 + +--------------------------------------+--------------------------------------+--------------------------------------+----------+ + | ID | Volume ID | Server ID | Status | + +--------------------------------------+--------------------------------------+--------------------------------------+----------+ + | d338fb38-cfd5-461f-8753-145dcbdb6c78 | 8b9b3491-f083-4485-8374-258372f3db35 | 216f9481-4c9d-4530-b865-51cedfa4b8e7 | attached | + +--------------------------------------+--------------------------------------+--------------------------------------+----------+ + +Show the details of a Cinder volume attachment from microversion >= 3.27: + +.. code-block:: shell + + $ openstack --os-volume-api-version 3.27 volume attachment show d338fb38-cfd5-461f-8753-145dcbdb6c78 + +-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Field | Value | + +-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ID | d338fb38-cfd5-461f-8753-145dcbdb6c78 | + | Volume ID | 8b9b3491-f083-4485-8374-258372f3db35 | + | Instance ID | 216f9481-4c9d-4530-b865-51cedfa4b8e7 | + | Status | attached | + | Attach Mode | rw | + | Attached At | 2021-09-14T13:03:38.000000 | + | Detached At | | + | Properties | access_mode='rw', attachment_id='d338fb38-cfd5-461f-8753-145dcbdb6c78', auth_method='CHAP', auth_password='4XyNNFV2TLPhKXoP', auth_username='jsBMQhWZJXupA4eWHLQG', cacheable='False', driver_volume_type='iscsi', encrypted='False', qos_specs=, target_discovered='False', target_iqn='iqn.2010-10.org.openstack:volume-8b9b3491-f083-4485-8374-258372f3db35', target_lun='0', target_portal='192.168.122.99:3260', volume_id='8b9b3491-f083-4485-8374-258372f3db35' | + +-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Refresh a volume attachment with nova-manage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 24.0.0 (Xena) + +Admins may also refresh an existing volume attachment using the following +:program:`nova-manage` commands. + +.. note:: + + Users can also refresh volume attachments by shelving and later unshelving + their instances. The following is an alternative to that workflow and + useful for admins when having to mass refresh attachments across an + environment. + +.. note:: + + Future work will look into introducing an os-refresh admin API that will + include orchestrating the shutdown of an instance and refreshing volume + attachments among other things. + +To begin the admin can use the `volume_attachment show` subcommand to dump +existing details of the attachment directly from the Nova database. This +includes the stashed `connection_info` not shared by the API. + +.. code-block:: shell + + $ nova-manage volume_attachment show 216f9481-4c9d-4530-b865-51cedfa4b8e7 8b9b3491-f083-4485-8374-258372f3db35 --json | jq .attachment_id + "d338fb38-cfd5-461f-8753-145dcbdb6c78" + +If the stored `connection_info` or `attachment_id` are incorrect then the +admin may want to refresh the attachment to the compute host entirely by +recreating the Cinder volume attachment record(s) and pulling down fresh +`connection_info`. To do this we first need to ensure the instance is stopped: + +.. code-block:: shell + + $ openstack server stop 216f9481-4c9d-4530-b865-51cedfa4b8e7 + +Once stopped the host connector of the compute hosting the instance has to be +fetched using the `volume_attachment get_connector` subcommand: + +.. code-block:: shell + + root@compute $ nova-manage volume_attachment get_connector --json > connector.json + +.. note:: + + Future work will remove this requirement and incorperate the gathering of + the host connector into the main refresh command. Unfortunatley until then + it must remain a seperate manual step. + +We can then provide this connector to the `volume_attachment refresh` +subcommand. This command will connect to the compute, disconnect any host +volume connections, delete the existing Cinder volume attachment, +recreate the volume attachment and finally update Nova's database. + +.. code-block:: shell + + $ nova-manage volume_attachment refresh 216f9481-4c9d-4530-b865-51cedfa4b8e7 8b9b3491-f083-4485-8374-258372f3db35 connector.json + +The Cinder volume attachment and connection_info stored in the Nova database +should now be updated: + +.. code-block:: shell + + $ nova-manage volume_attachment show 216f9481-4c9d-4530-b865-51cedfa4b8e7 8b9b3491-f083-4485-8374-258372f3db35 --json | jq .attachment_id + "9ce46f49-5cfc-4c6c-b2f0-0287540d3246" + +The instance can then be restarted and the event list checked + +.. code-block:: shell + + $ openstack server start $instance