From f3fa4eef4cb0f51f1f480302f31b0dab4e27107d Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Fri, 24 Aug 2018 17:47:01 -0400 Subject: [PATCH] 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 --- api-ref/source/os-volume-attachments.inc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/api-ref/source/os-volume-attachments.inc b/api-ref/source/os-volume-attachments.inc index 52a2aecde5bb..7cc8fa69187b 100644 --- a/api-ref/source/os-volume-attachments.inc +++ b/api-ref/source/os-volume-attachments.inc @@ -145,6 +145,16 @@ 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:: 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 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, + 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 defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.