From 606a5dfecce02d564d6245f57359efbf89b780da Mon Sep 17 00:00:00 2001 From: Lee Yarwood Date: Mon, 21 Dec 2020 16:13:51 +0000 Subject: [PATCH] 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 --- api-ref/source/os-volume-attachments.inc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/api-ref/source/os-volume-attachments.inc b/api-ref/source/os-volume-attachments.inc index 5ca5432b71ed..0ebc0cb75ef1 100644 --- a/api-ref/source/os-volume-attachments.inc +++ b/api-ref/source/os-volume-attachments.inc @@ -70,6 +70,10 @@ Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNo 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 ------- @@ -247,6 +251,11 @@ Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNo .. 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 -------