openstack/nova
Code Issues Proposed changes
521af26209
nova/api-ref/source/os-volume-attachments.inc

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

275 lines
8.6 KiB
PHP
Raw Normal View History

Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
.. -*- rst -*-
===================================================================
Servers with volume attachments (servers, os-volume\_attachments)
===================================================================
Attaches volumes that are created through the volume API to server
Fix 'server' and 'instance' occurrence in api-ref some api-ref have sentence like '..for a server instance' which is inconsistent and confusing as we use server for VM terminology. I think here 'instance' word is being considered object of server which is wrong. We should always mention server only. part of bp:api-ref-in-rst-pike Change-Id: I32afe56cfc66b34b76d1f7e1b507d3d5e722e6a1
2017-03-27 09:22:10 +00:00
instances. Also, lists volume attachments for a server, shows
Import RST files for documentation This is the results of the RST conversion from WADL. It creates a single index plus a bunch of included files which represent sections of the API document. This is the starting point for fixing the documentation. Change-Id: I7d561c2ecdcd864172dedb54a551f17ad3bdfe26
2016-04-12 09:03:46 -04:00
details for a volume attachment, and detaches a volume.
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
List volume attachments for an instance
=======================================
remove /v2.1/{tenant_id} from all urls As discussed at summit, the version part of the URL is not really relevant, or a thing a user should be filling out themselves, this should instead be set by the service catalog and extracted from the token. This removes it's reference in all documented REST urls, and adds a new section describing how one gets the base URL for all calls. Change-Id: I4306b8c3de0225e54f3909dd8a1fb293c4e5944c
2016-06-02 08:50:03 -04:00
.. rest_method:: GET /servers/{server_id}/os-volume_attachments
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
List volume attachments for an instance.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Add offset & limit docs & tests A number of endpoints enable pagination via 'limit' & 'offset' query parameters, but don't document or test this functionality. - os-cells - os-security-groups - os-server-groups - os-snapshots - os-virtual-interfaces - os-volume-attachments - os-volumes Change-Id: I5b0ad25f7282f4a13bbb6f21b76e986e1008936a
2016-12-15 13:20:32 -05:00
- limit: limit_simple
- offset: offset_simple
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Response
--------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- volumeAttachments: volumeAttachments
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
- id: volume_attachment_id_resp
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
- serverId: server_id
- volumeId: volumeId_resp
api-ref: mark device response param as optional for list/show vol attachments The 'device' response parameter is not included in GET /servers/{server_id}/os-volume_attachments or GET /servers/{server_id}/os-volume_attachments/{volume_id} when the BDM doesn't have a device_name set, which can be the case with a volume attached to a shelved offloaded server. Also, see the logic in _translate_attachment_detail_view and _translate_attachment_summary_view. This simply marks the response parameter as optional in those APIs. Since the parameter is optional, it is sorted to after the required parameters but before the parameters added in new microversions. Change-Id: Ifda2f7983f349d51d97e5621cac6c5ad9cb0295f Closes-Bug: #1818345
2019-10-22 15:22:28 -04:00
- device: attachment_device_resp
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
- tag: device_tag_bdm_attachment_resp
Add delete_on_termination to volume-attach API Add the 'delete_on_termination' field to the volume attach API to support configuring whether to delete the data volume when the instance is destroyed. To avoid upgrade impact issues with older computes, the 'delete_on_termination' field is set in the API rather than when the BDM is created in the compute service. Implements: blueprint support-delete-on-termination-in-server-attach-volume Change-Id: I55731b1822a4e32909665a2872d80895cb5b12f7
2019-07-27 18:16:36 +08:00
- delete_on_termination: delete_on_termination_attachments_resp
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
- attachment_id: attachment_volume_id_resp
- bdm_uuid: attachment_bdm_id_resp
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
api-ref: Example verification for os-volume_attachments.inc Change-Id: I1f5ba0453b0dc964f48471e4aecaaaa800699da1 Implements: blueprint api-ref-in-rst
2016-05-13 14:40:24 +09:00
**Example List volume attachments for an instance: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/list-volume-attachments-resp.json
:language: javascript
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
**Example List tagged volume attachments for an instance (v2.89): JSON response**
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.89/list-volume-attachments-resp.json
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
:language: javascript
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Attach a volume to an instance
==============================
remove /v2.1/{tenant_id} from all urls As discussed at summit, the version part of the URL is not really relevant, or a thing a user should be filling out themselves, this should instead be set by the service catalog and extracted from the token. This removes it's reference in all documented REST urls, and adds a new section describing how one gets the base URL for all calls. Change-Id: I4306b8c3de0225e54f3909dd8a1fb293c4e5944c
2016-06-02 08:50:03 -04:00
.. rest_method:: POST /servers/{server_id}/os-volume_attachments
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Attach a volume to an instance.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Add description for v2.20 changes in api-ref v2.20 allows shelved and shelve_offload instance to attach and detach volume, add descriptions for that Implements: blueprint api-ref-in-rst-ocata Change-Id: Ib1349c2ef9d69cfc74212fd48ff10f913a5ce134
2016-09-09 22:01:00 +08:00
.. 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.
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Request
-------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
api-ref: fix description of volumeAttachment for attach/swap-volume The description of the volumeAttachment request parameter was actually the description of the response parameter, which included more fields than we allow on the POST and PUT requests for os-volume_attachments. This fixes the descriptions for both POST and PUT and also includes a tiny fix for the wording on the existing volumeAttachment parameter. Change-Id: I4ccd4ac12e24b232925875fdb5fb568c2bfaf417 Closes-Bug: #1675536
2017-03-23 16:00:46 -04:00
- volumeAttachment: volumeAttachment_post
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
- volumeId: volumeId
- device: device
API support for tagged device attachment This patch adds microversion 2.49, which supports tagged attachment of network interfaces and block devices. Change-Id: I8d3bbe7e9a21d2694d10ee89628deb333e6b0487 Implements: blueprint virt-device-tagged-attach-detach
2016-09-25 10:00:43 -04:00
- tag: device_tag_bdm_attachment
Add delete_on_termination to volume-attach API Add the 'delete_on_termination' field to the volume attach API to support configuring whether to delete the data volume when the instance is destroyed. To avoid upgrade impact issues with older computes, the 'delete_on_termination' field is set in the API rather than when the BDM is created in the compute service. Implements: blueprint support-delete-on-termination-in-server-attach-volume Change-Id: I55731b1822a4e32909665a2872d80895cb5b12f7
2019-07-27 18:16:36 +08:00
- delete_on_termination: delete_on_termination_attachments_req
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
api-ref: Example verification for os-volume_attachments.inc Change-Id: I1f5ba0453b0dc964f48471e4aecaaaa800699da1 Implements: blueprint api-ref-in-rst
2016-05-13 14:40:24 +09:00
**Example Attach a volume to an instance: JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/attach-volume-to-server-req.json
:language: javascript
API support for tagged device attachment This patch adds microversion 2.49, which supports tagged attachment of network interfaces and block devices. Change-Id: I8d3bbe7e9a21d2694d10ee89628deb333e6b0487 Implements: blueprint virt-device-tagged-attach-detach
2016-09-25 10:00:43 -04:00
**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
Add delete_on_termination to volume-attach API Add the 'delete_on_termination' field to the volume attach API to support configuring whether to delete the data volume when the instance is destroyed. To avoid upgrade impact issues with older computes, the 'delete_on_termination' field is set in the API rather than when the BDM is created in the compute service. Implements: blueprint support-delete-on-termination-in-server-attach-volume Change-Id: I55731b1822a4e32909665a2872d80895cb5b12f7
2019-07-27 18:16:36 +08:00
**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
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Response
--------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- volumeAttachment: volumeAttachment
- device: device_resp
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
- id: attachment_id_resp
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
- serverId: server_id
- volumeId: volumeId_resp
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
- tag: device_tag_bdm_attachment_resp
Add delete_on_termination to volume-attach API Add the 'delete_on_termination' field to the volume attach API to support configuring whether to delete the data volume when the instance is destroyed. To avoid upgrade impact issues with older computes, the 'delete_on_termination' field is set in the API rather than when the BDM is created in the compute service. Implements: blueprint support-delete-on-termination-in-server-attach-volume Change-Id: I55731b1822a4e32909665a2872d80895cb5b12f7
2019-07-27 18:16:36 +08:00
- delete_on_termination: delete_on_termination_attachments_resp
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
api-ref: Example verification for os-volume_attachments.inc Change-Id: I1f5ba0453b0dc964f48471e4aecaaaa800699da1 Implements: blueprint api-ref-in-rst
2016-05-13 14:40:24 +09:00
**Example Attach a volume to an instance: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/attach-volume-to-server-resp.json
:language: javascript
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
**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
Add delete_on_termination to volume-attach API Add the 'delete_on_termination' field to the volume attach API to support configuring whether to delete the data volume when the instance is destroyed. To avoid upgrade impact issues with older computes, the 'delete_on_termination' field is set in the API rather than when the BDM is created in the compute service. Implements: blueprint support-delete-on-termination-in-server-attach-volume Change-Id: I55731b1822a4e32909665a2872d80895cb5b12f7
2019-07-27 18:16:36 +08:00
**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
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Show a detail of a volume attachment
====================================
Fix parameters and description for os-volume_attachments Now the code implementation for the api show and delete for os-volume_attachments and the description of the document does not match. Change-Id: Ib15532d628713d771a835e9825a1c699a7ea4fcb
2017-07-06 13:26:39 +08:00
.. rest_method:: GET /servers/{server_id}/os-volume_attachments/{volume_id}
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Show a detail of a volume attachment.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
api-ref: Fix parameters for os-volume-attachments.inc In the following APIs, the 'volume_id' parameters are 'path' parameters. So fix them. - GET /servers/{server_id}/os-volume_attachments/{volume_id} - DELETE /servers/{server_id}/os-volume_attachments/{volume_id} In addition, the descriptions of the parameters are amended. Change-Id: Iab93acde31639b1471c83b06fb1a77474bb52c48 Closes-Bug: #1770560
2018-05-11 14:12:56 +09:00
- volume_id: volume_id_attached_path
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Response
--------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- volumeAttachment: volumeAttachment
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
- id: volume_attachment_id_resp
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
- serverId: server_id
- volumeId: volumeId_resp
api-ref: mark device response param as optional for list/show vol attachments The 'device' response parameter is not included in GET /servers/{server_id}/os-volume_attachments or GET /servers/{server_id}/os-volume_attachments/{volume_id} when the BDM doesn't have a device_name set, which can be the case with a volume attached to a shelved offloaded server. Also, see the logic in _translate_attachment_detail_view and _translate_attachment_summary_view. This simply marks the response parameter as optional in those APIs. Since the parameter is optional, it is sorted to after the required parameters but before the parameters added in new microversions. Change-Id: Ifda2f7983f349d51d97e5621cac6c5ad9cb0295f Closes-Bug: #1818345
2019-10-22 15:22:28 -04:00
- device: attachment_device_resp
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
- tag: device_tag_bdm_attachment_resp
Add delete_on_termination to volume-attach API Add the 'delete_on_termination' field to the volume attach API to support configuring whether to delete the data volume when the instance is destroyed. To avoid upgrade impact issues with older computes, the 'delete_on_termination' field is set in the API rather than when the BDM is created in the compute service. Implements: blueprint support-delete-on-termination-in-server-attach-volume Change-Id: I55731b1822a4e32909665a2872d80895cb5b12f7
2019-07-27 18:16:36 +08:00
- delete_on_termination: delete_on_termination_attachments_resp
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
- attachment_id: attachment_volume_id_resp
- bdm_uuid: attachment_bdm_id_resp
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
api-ref: Example verification for os-volume_attachments.inc Change-Id: I1f5ba0453b0dc964f48471e4aecaaaa800699da1 Implements: blueprint api-ref-in-rst
2016-05-13 14:40:24 +09:00
**Example Show a detail of a volume attachment: JSON response**
.. literalinclude:: ../../doc/api_samples/os-volumes/volume-attachment-detail-resp.json
:language: javascript
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
**Example Show a detail of a tagged volume attachment (v2.89): JSON response**
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
api: Introduce microversion 2.89 adjusting os-volume_attachments This microversion adds attachment_id and bdm_uuid as stored in the underlying bdm record while also removing the duplicate id field from the responses of ``GET /servers/{server_id}/os-volume_attachments`` and ``GET /servers/{server_id}/os-volume_attachments/{volume_id}``. To accomidate this within the _translate_attachment_summary_view helper is folded into _translate_attachment_detail_view with the remaining caller in the now deprecated os-volumes API now replaced with a static dictionary. Blueprint: add-attachmentid-to-responses-of-the-os-volume-attachments-api Change-Id: I977c3fd9bbb1e1d42e6979222137e7366d2815e8
2021-08-11 14:14:12 +01:00
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.89/volume-attachment-detail-resp.json
Add microversion to expose virtual device tags This change adds a new microversion to expose virtual device tags for volumes and ports attached to a server. Implements blueprint expose-virtual-device-tags-in-rest-api Change-Id: I09420ff7134874dfe4dc399931c7740e81ecc2d0
2019-01-19 21:11:32 -05:00
:language: javascript
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Update a volume attachment
==========================
Update the parameter explain when updating a volume attachment When we update a volume attachment in nova api, we use volume_id instead of attachment_id in params in latest api. Change-Id: I5fc4d0ba3bb1c49dfaba2b2eed056441509cb9da
2018-04-30 18:10:41 +08:00
.. rest_method:: PUT /servers/{server_id}/os-volume_attachments/{volume_id}
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Update a volume attachment.
Do not attempt volume swap when guest is stopped/suspended A swap on a stopped or suspended instance will fail silently. Remove these allowed instance states on swap_volume: suspended, stopped, soft_deleted Change-Id: Iff17f7cee7a56037b35d1a361a0b3279d0a885d6 Closes-Bug: #1673090
2017-07-24 12:46:21 -04:00
.. note:: This action only valid when the server is in ACTIVE, PAUSED and RESIZED state,
or a conflict(409) error will be returned.
Allow PUT volume attachments API to modify delete_on_termination Allow PUT /servers/{server_id}/os-volume_attachments/{volume_id}`` to support specifying ``delete_on_termination`` field in the request body. This allows updating the attached volume's flag that controls whether or not it is automatically deleted when the instance is deleted. When we request 'volumeId' and 'delete_on_termination' in the requst body to swap volume, since the new microversion it will be support updating the swapping volume's delete flag. Co-Authored-By: Dan Smith <dansmith@redhat.com> Blueprint: destroy-instance-with-datavolume Change-Id: I6ccac4e17f56b40e67c79d40f32558ef414685ea
2019-11-12 20:00:54 +08:00
.. 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`_.
api-ref: add a warning about calling swap volume directly Per the ML thread on this [1] we should have a warning in the API discouraging people from swapping volumes directly in nova. [1] http://lists.openstack.org/pipermail/openstack-dev/2018-August/133527.html Change-Id: If095e1d9bae8be7a23212684ed9d2e043c0cbf59
2018-08-24 17:47:01 -04:00
.. _certain compute drivers: https://docs.openstack.org/nova/latest/user/support-matrix.html#operation_swap_volume
Allow PUT volume attachments API to modify delete_on_termination Allow PUT /servers/{server_id}/os-volume_attachments/{volume_id}`` to support specifying ``delete_on_termination`` field in the request body. This allows updating the attached volume's flag that controls whether or not it is automatically deleted when the instance is deleted. When we request 'volumeId' and 'delete_on_termination' in the requst body to swap volume, since the new microversion it will be support updating the swapping volume's delete flag. Co-Authored-By: Dan Smith <dansmith@redhat.com> Blueprint: destroy-instance-with-datavolume Change-Id: I6ccac4e17f56b40e67c79d40f32558ef414685ea
2019-11-12 20:00:54 +08:00
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.
Update the parameter explain when updating a volume attachment When we update a volume attachment in nova api, we use volume_id instead of attachment_id in params in latest api. Change-Id: I5fc4d0ba3bb1c49dfaba2b2eed056441509cb9da
2018-04-30 18:10:41 +08:00
Block swap volume on volumes with >1 rw attachment If we're swapping from a multiattach volume that has more than one read/write attachment, another server on the secondary attachment could be writing to the volume which is not getting copied into the volume to which we're swapping, so we could have data loss during the swap. This change does volume read/write attachment counting for the volume we're swapping from and if there is more than one read/write attachment on the volume, the swap volume operation fails with a 400 BadRequest error. Depends-On: https://review.openstack.org/573025/ Closes-Bug: #1775418 Change-Id: Icd7fcb87a09c35a13e4e14235feb30a289d22778
2018-06-06 10:32:37 -04:00
Updating, or what is commonly referred to as "swapping", volume attachments
with volumes that have more than one read/write attachment, is not supported.
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Request
-------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
Update the parameter explain when updating a volume attachment When we update a volume attachment in nova api, we use volume_id instead of attachment_id in params in latest api. Change-Id: I5fc4d0ba3bb1c49dfaba2b2eed056441509cb9da
2018-04-30 18:10:41 +08:00
- volume_id: volume_id_swap_src
api-ref: fix description of volumeAttachment for attach/swap-volume The description of the volumeAttachment request parameter was actually the description of the response parameter, which included more fields than we allow on the POST and PUT requests for os-volume_attachments. This fixes the descriptions for both POST and PUT and also includes a tiny fix for the wording on the existing volumeAttachment parameter. Change-Id: I4ccd4ac12e24b232925875fdb5fb568c2bfaf417 Closes-Bug: #1675536
2017-03-23 16:00:46 -04:00
- volumeAttachment: volumeAttachment_put
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
- volumeId: volumeId_swap
Allow PUT volume attachments API to modify delete_on_termination Allow PUT /servers/{server_id}/os-volume_attachments/{volume_id}`` to support specifying ``delete_on_termination`` field in the request body. This allows updating the attached volume's flag that controls whether or not it is automatically deleted when the instance is deleted. When we request 'volumeId' and 'delete_on_termination' in the requst body to swap volume, since the new microversion it will be support updating the swapping volume's delete flag. Co-Authored-By: Dan Smith <dansmith@redhat.com> Blueprint: destroy-instance-with-datavolume Change-Id: I6ccac4e17f56b40e67c79d40f32558ef414685ea
2019-11-12 20:00:54 +08:00
- 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
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
Allow PUT volume attachments API to modify delete_on_termination Allow PUT /servers/{server_id}/os-volume_attachments/{volume_id}`` to support specifying ``delete_on_termination`` field in the request body. This allows updating the attached volume's flag that controls whether or not it is automatically deleted when the instance is deleted. When we request 'volumeId' and 'delete_on_termination' in the requst body to swap volume, since the new microversion it will be support updating the swapping volume's delete flag. Co-Authored-By: Dan Smith <dansmith@redhat.com> Blueprint: destroy-instance-with-datavolume Change-Id: I6ccac4e17f56b40e67c79d40f32558ef414685ea
2019-11-12 20:00:54 +08:00
.. note:: Other than ``volumeId``, as of v2.85 only
``delete_on_termination`` may be changed from the current
value.
api-ref: Example verification for os-volume_attachments.inc Change-Id: I1f5ba0453b0dc964f48471e4aecaaaa800699da1 Implements: blueprint api-ref-in-rst
2016-05-13 14:40:24 +09:00
Allow PUT volume attachments API to modify delete_on_termination Allow PUT /servers/{server_id}/os-volume_attachments/{volume_id}`` to support specifying ``delete_on_termination`` field in the request body. This allows updating the attached volume's flag that controls whether or not it is automatically deleted when the instance is deleted. When we request 'volumeId' and 'delete_on_termination' in the requst body to swap volume, since the new microversion it will be support updating the swapping volume's delete flag. Co-Authored-By: Dan Smith <dansmith@redhat.com> Blueprint: destroy-instance-with-datavolume Change-Id: I6ccac4e17f56b40e67c79d40f32558ef414685ea
2019-11-12 20:00:54 +08:00
**Example Update a volume attachment (v2.85): JSON request**
.. literalinclude:: ../../doc/api_samples/os-volumes/v2.85/update-volume-attachment-delete-flag-req.json
api-ref: Example verification for os-volume_attachments.inc Change-Id: I1f5ba0453b0dc964f48471e4aecaaaa800699da1 Implements: blueprint api-ref-in-rst
2016-05-13 14:40:24 +09:00
:language: javascript
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Response
--------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
No body is returned on successful request.
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Detach a volume from an instance
================================
Fix parameters and description for os-volume_attachments Now the code implementation for the api show and delete for os-volume_attachments and the description of the document does not match. Change-Id: Ib15532d628713d771a835e9825a1c699a7ea4fcb
2017-07-06 13:26:39 +08:00
.. rest_method:: DELETE /servers/{server_id}/os-volume_attachments/{volume_id}
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Detach a volume from an instance.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
Add description for v2.20 changes in api-ref v2.20 allows shelved and shelve_offload instance to attach and detach volume, add descriptions for that Implements: blueprint api-ref-in-rst-ocata Change-Id: Ib1349c2ef9d69cfc74212fd48ff10f913a5ce134
2016-09-09 22:01:00 +08:00
.. 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.
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Request
-------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
.. rest_parameters:: parameters.yaml
- server_id: server_id_path
api-ref: Fix parameters for os-volume-attachments.inc In the following APIs, the 'volume_id' parameters are 'path' parameters. So fix them. - GET /servers/{server_id}/os-volume_attachments/{volume_id} - DELETE /servers/{server_id}/os-volume_attachments/{volume_id} In addition, the descriptions of the parameters are amended. Change-Id: Iab93acde31639b1471c83b06fb1a77474bb52c48 Closes-Bug: #1770560
2018-05-11 14:12:56 +09:00
- volume_id: volume_id_to_detach_path
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
api-ref: Method verification for os-volume_attachments.inc Change-Id: I560908b28c1193622ee6e042322024fc6d0df5d6 Implements: blueprint api-ref-in-rst
2016-05-12 08:19:24 +09:00
Response
--------
api-ref: Parameter verification for os-volume_attachments.inc Change-Id: I3789a4ad36e30728024f2aa122403b0e53b1e741 Implements: blueprint api-ref-in-rst
2016-05-13 12:51:09 +09:00
No body is returned on successful request.
Copy Permalink