Files
bed227c33a59d0407905056e01c923129c3d324c
nova /api-ref /source /os-volume-attachments.inc

275 lines
8.6 KiB
PHP
Raw Normal View History

.. -*- rst -*-
===================================================================
Servers with volume attachments (servers, os-volume\_attachments)
===================================================================
Attaches volumes that are created through the volume API to server
instances. Also, lists volume attachments for a server, shows
details for a volume attachment, and detaches a volume.
List volume attachments for an instance
=======================================
.. rest_method:: GET /servers/{server_id}/os-volume_attachments
List volume attachments for an instance.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- limit: limit_simple
- offset: offset_simple
Response
--------
.. rest_parameters:: parameters.yaml
- volumeAttachments: volumeAttachments
- id: volume_attachment_id_resp
- serverId: server_id
- volumeId: volumeId_resp
- device: attachment_device_resp
- tag: device_tag_bdm_attachment_resp
- delete_on_termination: delete_on_termination_attachments_resp
- attachment_id: attachment_volume_id_resp
- bdm_uuid: attachment_bdm_id_resp
**Example List volume attachments for an instance: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/list-volume-attachments-resp.json
:language: javascript
**Example List tagged volume attachments for an instance (v2.89): JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.89/list-volume-attachments-resp.json
:language: javascript
Attach a volume to an instance
==============================
.. rest_method:: POST /servers/{server_id}/os-volume_attachments
Attach a volume to an instance.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
.. note:: From v2.20 attach a volume to an instance in SHELVED or SHELVED_OFFLOADED
state is allowed.
[api] Allow multi-attach in compute api This change introduces a new microversion which must be used to create a server from a multiattach volume or attach a multiattach volume to an existing server instance. Attaching a multiattach volume to a shelved offloaded instance is not supported since an instance in that state does not have a compute host so we can't tell if the compute would support the multiattach volume or not. This is consistent with the tagged attach validation with 2.49. When creating a server from a multiattach volume, we'll check to see if all computes in all cells are upgraded to the point of even supporting the compute side changes, otherwise the server create request fails with a 409. We do this because we don't know which compute node the scheduler will pick and we don't have any compute capability filtering in the scheduler for multiattach volumes (that may be a future improvement). Similarly, when attaching a multiattach volume to an existing instance, if the compute isn't new enough to support multiattach or the virt driver simply doesn't support the capability, a 409 response is returned. Presumably, operators will use AZs/aggregates to organize which hosts support multiattach if they have a mixed hypervisor deployment, or will simply disable multiattach support via Cinder policy. The unit tests are covering error conditions with the new flow. A new functional scenario test is added for happy path testing of the new boot from multiattach volume flow and attaching a multiattach volume to more than one instance. Tempest integration testing for multiattach is added in change I80c20914c03d7371e798ca3567c37307a0d54aaa. Devstack support for multiattach is added in change I46b7eabf6a28f230666f6933a087f73cb4408348. Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Implements: blueprint multi-attach-volume Change-Id: I02120ef8767c3f9c9497bff67101e57e204ed6f4
2016年01月21日 22:10:27 +01:00
.. note:: From v2.60, attaching a multiattach volume to multiple instances is
supported for instances that are not SHELVED_OFFLOADED. The ability
to actually support a multiattach volume depends on the volume type
and compute hosting the instance.
api-ref: Add notes about volume attach and detach being async This change adds some basic notes in the api-ref for a wrinkle in the current os-volume_attachments API in that both attach and detach actions are async, returning to the caller *before* the underlying action is complete. As such callers need to make seperate calls to ensure these actions complete successfully. There are also currently two different ways of polling for completion when attaching and detaching. - When attaching callers should use the volume status and list of attachments as reported by the volume API. - When detaching callers should instead use the list of volume attachments reported by the os-volume_attachments API. This is due to the way in which Nova currently completes the attachment via c-api last during attachment and deletes the bdm record last during detachment. It would be useful to one day centralise on just using the os-volume_attachments API to poll both actions but to do that we would need to start tracking our own state within the BDMs. Change-Id: Id367ee53ef1458b6a90fc107ab14f5b3cbba7a86
2020年12月21日 16:13:51 +00:00
.. note:: This is an asynchronous API, callers should poll the status and list
of attachments of the volume within the volume API to determine when
the attachment has completed successfully.
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- volumeAttachment: volumeAttachment_post
- volumeId: volumeId
- device: device
- tag: device_tag_bdm_attachment
- delete_on_termination: delete_on_termination_attachments_req
**Example Attach a volume to an instance: JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/attach-volume-to-server-req.json
:language: javascript
**Example Attach a volume to an instance and tag it (v2.49): JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.49/attach-volume-to-server-req.json
:language: javascript
**Example Attach a volume to an instance with "delete_on_termination" (v2.79): JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.79/attach-volume-to-server-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- volumeAttachment: volumeAttachment
- device: device_resp
- id: attachment_id_resp
- serverId: server_id
- volumeId: volumeId_resp
- tag: device_tag_bdm_attachment_resp
- delete_on_termination: delete_on_termination_attachments_resp
**Example Attach a volume to an instance: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/attach-volume-to-server-resp.json
:language: javascript
**Example Attach a tagged volume to an instance (v2.70): JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.70/attach-volume-to-server-resp.json
:language: javascript
**Example Attach a volume with "delete_on_termination" (v2.79): JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.79/attach-volume-to-server-resp.json
:language: javascript
Show a detail of a volume attachment
====================================
.. rest_method:: GET /servers/{server_id}/os-volume_attachments/{volume_id}
Show a detail of a volume attachment.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- volume_id: volume_id_attached_path
Response
--------
.. rest_parameters:: parameters.yaml
- volumeAttachment: volumeAttachment
- id: volume_attachment_id_resp
- serverId: server_id
- volumeId: volumeId_resp
- device: attachment_device_resp
- tag: device_tag_bdm_attachment_resp
- delete_on_termination: delete_on_termination_attachments_resp
- attachment_id: attachment_volume_id_resp
- bdm_uuid: attachment_bdm_id_resp
**Example Show a detail of a volume attachment: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/volume-attachment-detail-resp.json
:language: javascript
**Example Show a detail of a tagged volume attachment (v2.89): JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.89/volume-attachment-detail-resp.json
:language: javascript
Update a volume attachment
==========================
.. rest_method:: PUT /servers/{server_id}/os-volume_attachments/{volume_id}
Update a volume attachment.
.. note:: This action only valid when the server is in ACTIVE, PAUSED and RESIZED state,
or a conflict(409) error will be returned.
.. warning:: When updating volumeId, this API is typically meant to
only be used as part of a larger orchestrated volume
migration operation initiated in the block storage
service via the ``os-retype`` or ``os-migrate_volume``
volume actions. Direct usage of this API to update
volumeId is not recommended and may result in needing to
hard reboot the server to update details within the guest
such as block storage serial IDs. Furthermore, updating
volumeId via this API is only implemented by `certain
compute drivers`_.
.. _certain compute drivers: https://docs.openstack.org/nova/latest/user/support-matrix.html#operation_swap_volume
Policy default role is 'rule:system_admin_or_owner', its scope is
[system, project], which allow project members or system admins to
change the fields of an attached volume of a server. Policy defaults
enable only users with the administrative role to change ``volumeId``
via this operation. Cloud providers can change these permissions
through the ``policy.json`` file.
Updating, or what is commonly referred to as "swapping", volume attachments
with volumes that have more than one read/write attachment, is not supported.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- volume_id: volume_id_swap_src
- volumeAttachment: volumeAttachment_put
- volumeId: volumeId_swap
- delete_on_termination: delete_on_termination_put_req
- device: attachment_device_put_req
- serverId: attachment_server_id_put_req
- tag: device_tag_bdm_attachment_put_req
- id: attachment_id_put_req
.. note:: Other than ``volumeId``, as of v2.85 only
``delete_on_termination`` may be changed from the current
value.
**Example Update a volume attachment (v2.85): JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.85/update-volume-attachment-delete-flag-req.json
:language: javascript
Response
--------
No body is returned on successful request.
Detach a volume from an instance
================================
.. rest_method:: DELETE /servers/{server_id}/os-volume_attachments/{volume_id}
Detach a volume from an instance.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
.. note:: From v2.20 detach a volume from an instance in SHELVED or SHELVED_OFFLOADED
state is allowed.
api-ref: Add notes about volume attach and detach being async This change adds some basic notes in the api-ref for a wrinkle in the current os-volume_attachments API in that both attach and detach actions are async, returning to the caller *before* the underlying action is complete. As such callers need to make seperate calls to ensure these actions complete successfully. There are also currently two different ways of polling for completion when attaching and detaching. - When attaching callers should use the volume status and list of attachments as reported by the volume API. - When detaching callers should instead use the list of volume attachments reported by the os-volume_attachments API. This is due to the way in which Nova currently completes the attachment via c-api last during attachment and deletes the bdm record last during detachment. It would be useful to one day centralise on just using the os-volume_attachments API to poll both actions but to do that we would need to start tracking our own state within the BDMs. Change-Id: Id367ee53ef1458b6a90fc107ab14f5b3cbba7a86
2020年12月21日 16:13:51 +00:00
.. note:: This is an asynchronous API, callers should poll the list
of volume attachments provided by ``GET
/servers/{server_id}/os-volume_attachments`` to determine when the
detachment of the volume has completed successfully.
Request
-------
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
- volume_id: volume_id_to_detach_path
Response
--------
No body is returned on successful request.