Skip to content

Commit d786577

Browse files
Zuulopenstack-gerrit
Zuul
authored and
openstack-gerrit
committed
Merge "docs: Add nova-volume volume_attachment refresh admin workflow"
2 parents 01eaa62 + 7004085 commit d786577

File tree

1 file changed

+143
-0
lines changed

1 file changed

+143
-0
lines changed

‎doc/source/admin/manage-volumes.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,146 @@ tests themselves, are defined in the `tempest repository`_.
7171
.. _added support for multiattach volumes: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/multi-attach-volume.html
7272
.. _recorded overview and demo: https://www.youtube.com/watch?v=hZg6wqxdEHk
7373
.. _tempest repository: http://codesearch.openstack.org/?q=CONF.compute_feature_enabled.volume_multiattach&i=nope&files=&repos=tempest
74+
75+
Managing volume attachments
76+
---------------------------
77+
78+
During the lifecycle of an instance admins may need to check various aspects of
79+
how a given volume is mapped both to an instance and the underlying compute
80+
hosting the instance. This could even include refreshing different elements of
81+
the attachment to ensure the latest configuration changes within the
82+
environment have been applied.
83+
84+
Checking an existing attachment
85+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
86+
87+
Existing volume attachments can be checked using the following
88+
:python-openstackclient-doc:`OpenStack Client commands <cli/command-objects>`:
89+
90+
List all volume attachments for a given instance:
91+
92+
.. code-block:: shell
93+
94+
$ openstack server volume list 216f9481-4c9d-4530-b865-51cedfa4b8e7
95+
+--------------------------------------+----------+--------------------------------------+--------------------------------------+
96+
| ID | Device | Server ID | Volume ID |
97+
+--------------------------------------+----------+--------------------------------------+--------------------------------------+
98+
| 8b9b3491-f083-4485-8374-258372f3db35 | /dev/vdb | 216f9481-4c9d-4530-b865-51cedfa4b8e7 | 8b9b3491-f083-4485-8374-258372f3db35 |
99+
+--------------------------------------+----------+--------------------------------------+--------------------------------------+
100+
101+
List all volume attachments for a given instance with the Cinder volume
102+
attachment and Block Device Mapping UUIDs also listed with microversion >=2.89:
103+
104+
.. code-block:: shell
105+
106+
$ openstack --os-compute-api-version 2.89 server volume list 216f9481-4c9d-4530-b865-51cedfa4b8e7
107+
+----------+--------------------------------------+--------------------------------------+------+------------------------+--------------------------------------+--------------------------------------+
108+
| Device | Server ID | Volume ID | Tag | Delete On Termination? | Attachment ID | BlockDeviceMapping UUID |
109+
+----------+--------------------------------------+--------------------------------------+------+------------------------+--------------------------------------+--------------------------------------+
110+
| /dev/vdb | 216f9481-4c9d-4530-b865-51cedfa4b8e7 | 8b9b3491-f083-4485-8374-258372f3db35 | None | False | d338fb38-cfd5-461f-8753-145dcbdb6c78 | 4e957e6d-52f2-44da-8cf8-3f1ab755e26d |
111+
+----------+--------------------------------------+--------------------------------------+------+------------------------+--------------------------------------+--------------------------------------+
112+
113+
List all Cinder volume attachments for a given volume from microversion >=
114+
3.27:
115+
116+
.. code-block:: shell
117+
118+
$ openstack --os-volume-api-version 3.27 volume attachment list --volume-id 8b9b3491-f083-4485-8374-258372f3db35
119+
+--------------------------------------+--------------------------------------+--------------------------------------+----------+
120+
| ID | Volume ID | Server ID | Status |
121+
+--------------------------------------+--------------------------------------+--------------------------------------+----------+
122+
| d338fb38-cfd5-461f-8753-145dcbdb6c78 | 8b9b3491-f083-4485-8374-258372f3db35 | 216f9481-4c9d-4530-b865-51cedfa4b8e7 | attached |
123+
+--------------------------------------+--------------------------------------+--------------------------------------+----------+
124+
125+
Show the details of a Cinder volume attachment from microversion >= 3.27:
126+
127+
.. code-block:: shell
128+
129+
$ openstack --os-volume-api-version 3.27 volume attachment show d338fb38-cfd5-461f-8753-145dcbdb6c78
130+
+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
131+
| Field | Value |
132+
+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
133+
| ID | d338fb38-cfd5-461f-8753-145dcbdb6c78 |
134+
| Volume ID | 8b9b3491-f083-4485-8374-258372f3db35 |
135+
| Instance ID | 216f9481-4c9d-4530-b865-51cedfa4b8e7 |
136+
| Status | attached |
137+
| Attach Mode | rw |
138+
| Attached At | 2021-09-14T13:03:38.000000 |
139+
| Detached At | |
140+
| 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' |
141+
+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
142+
143+
Refresh a volume attachment with nova-manage
144+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145+
146+
.. versionadded:: 24.0.0 (Xena)
147+
148+
Admins may also refresh an existing volume attachment using the following
149+
:program:`nova-manage` commands.
150+
151+
.. note::
152+
153+
Users can also refresh volume attachments by shelving and later unshelving
154+
their instances. The following is an alternative to that workflow and
155+
useful for admins when having to mass refresh attachments across an
156+
environment.
157+
158+
.. note::
159+
160+
Future work will look into introducing an os-refresh admin API that will
161+
include orchestrating the shutdown of an instance and refreshing volume
162+
attachments among other things.
163+
164+
To begin the admin can use the `volume_attachment show` subcommand to dump
165+
existing details of the attachment directly from the Nova database. This
166+
includes the stashed `connection_info` not shared by the API.
167+
168+
.. code-block:: shell
169+
170+
$ nova-manage volume_attachment show 216f9481-4c9d-4530-b865-51cedfa4b8e7 8b9b3491-f083-4485-8374-258372f3db35 --json | jq .attachment_id
171+
"d338fb38-cfd5-461f-8753-145dcbdb6c78"
172+
173+
If the stored `connection_info` or `attachment_id` are incorrect then the
174+
admin may want to refresh the attachment to the compute host entirely by
175+
recreating the Cinder volume attachment record(s) and pulling down fresh
176+
`connection_info`. To do this we first need to ensure the instance is stopped:
177+
178+
.. code-block:: shell
179+
180+
$ openstack server stop 216f9481-4c9d-4530-b865-51cedfa4b8e7
181+
182+
Once stopped the host connector of the compute hosting the instance has to be
183+
fetched using the `volume_attachment get_connector` subcommand:
184+
185+
.. code-block:: shell
186+
187+
root@compute $ nova-manage volume_attachment get_connector --json > connector.json
188+
189+
.. note::
190+
191+
Future work will remove this requirement and incorperate the gathering of
192+
the host connector into the main refresh command. Unfortunatley until then
193+
it must remain a seperate manual step.
194+
195+
We can then provide this connector to the `volume_attachment refresh`
196+
subcommand. This command will connect to the compute, disconnect any host
197+
volume connections, delete the existing Cinder volume attachment,
198+
recreate the volume attachment and finally update Nova's database.
199+
200+
.. code-block:: shell
201+
202+
$ nova-manage volume_attachment refresh 216f9481-4c9d-4530-b865-51cedfa4b8e7 8b9b3491-f083-4485-8374-258372f3db35 connector.json
203+
204+
The Cinder volume attachment and connection_info stored in the Nova database
205+
should now be updated:
206+
207+
.. code-block:: shell
208+
209+
$ nova-manage volume_attachment show 216f9481-4c9d-4530-b865-51cedfa4b8e7 8b9b3491-f083-4485-8374-258372f3db35 --json | jq .attachment_id
210+
"9ce46f49-5cfc-4c6c-b2f0-0287540d3246"
211+
212+
The instance can then be restarted and the event list checked
213+
214+
.. code-block:: shell
215+
216+
$ openstack server start $instance

0 commit comments

Comments
 (0)