Johannes Kulik
2a51df2760
Instead of returning an HTTP 200 and a `volumeAttachment` object, attaching a volume to an instance returns HTTP 202 starting from API version 2.101. To keep the functionality for older API versions, we move the `_attach_volume()` method from n-api to n-conductor and either do a call or a cast depending on whether the API needs to return a value. n-conductor then handles reserving the block_device_mapping's device by calling n-compute before it starts the previously-already-async volume attachment. We have to move `_check_attach_and_reserve_volume` into compute utils, because it's getting called in both conductor and compute api (for the shelved offloaded attach). The new RPC method in the conductor needs a long timeout when used with API versions less than the new 2.101, because it waits for the call to `reserve_block_device_name()` in nova-compute which already needs a long timeout. Updating the functional tests' `post_server_volume()` and `_attach_volume()` to not return the attachment anymore is possible, as no test uses the returned values. Change-Id: I4d38c2679f0e88cca30055a9c8c45ba1dd6fb5ef Implements: blueprint async-volume-attachments Signed-off-by: Johannes Kulik <johannes.kulik@sap.com>
258 lines
7.8 KiB
ReStructuredText
258 lines
7.8 KiB
ReStructuredText
.. -*- 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-volume_attachments/list-volume-attachments-resp.json
|
|
:language: javascript
|
|
|
|
**Example List tagged volume attachments for an instance (v2.89): JSON response**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-volume_attachments/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 (microversions 2.0 - 2.100), 202 (microversion 2.101 - )
|
|
|
|
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.
|
|
|
|
.. 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.
|
|
|
|
.. 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-volume_attachments/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-volume_attachments/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-volume_attachments/v2.79/attach-volume-to-server-req.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
Starting with microversion 2.101, there is no body content for the response of
|
|
a successful POST operation. Until microversion 2.100, a response contains the
|
|
following parameters.
|
|
|
|
.. 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-volume_attachments/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-volume_attachments/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-volume_attachments/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-volume_attachments/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-volume_attachments/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.
|
|
|
|
Policy default role is 'rule:admin_or_owner', its scope is [project], which
|
|
allow project members or admins to change the fields of an attached volume of
|
|
a server. Cloud providers can change these permissions through the
|
|
``policy.yaml`` file.
|
|
|
|
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_path
|
|
- volumeAttachment: volumeAttachment_put
|
|
- volumeId: volumeId_update
|
|
- 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-volume_attachments/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.
|
|
|
|
.. 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.
|