From 71ca8578be65594eb8eb985675bb988ca03f521b Mon Sep 17 00:00:00 2001 From: Lee Yarwood Date: Tue, 19 Feb 2019 13:47:15 +0000 Subject: [PATCH] docs: Add os-migrate_volume_completion api-ref This admin API is only called externally by Nova at present when finishing the migration or retype of an attached volume. However for future reference it would be really useful to have this listed in the official API reference guide. Change-Id: I5fad6eb4903784870aa26fa0996a391bbbbb9276 --- api-ref/source/v2/parameters.yaml | 18 +++++++ ...-os-migrate_volume_completion-request.json | 6 +++ .../source/v2/volumes-v2-volumes-actions.inc | 50 +++++++++++++++++++ api-ref/source/v3/parameters.yaml | 18 +++++++ ...-os-migrate_volume_completion-request.json | 6 +++ .../source/v3/volumes-v3-volumes-actions.inc | 50 +++++++++++++++++++ 6 files changed, 148 insertions(+) create mode 100644 api-ref/source/v2/samples/volume-os-migrate_volume_completion-request.json create mode 100644 api-ref/source/v3/samples/volume-os-migrate_volume_completion-request.json diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 63aefa9ed1d..89db86e2fb6 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -1040,6 +1040,12 @@ migrate_lock_volume: in: body required: false type: boolean +migration_completion_error: + description: | + Used to indicate if an error has occured elsewhere that requires clean up. + in: body + required: false + type: boolean # NOTE(mriedem): We can update the migration_policy retype note about encrypted # in-use volumes not being supported once # https://bugzilla.redhat.com/show_bug.cgi?id=760547 is fixed. @@ -1213,6 +1219,12 @@ new_type: in: body required: true type: string +new_volume: + description: | + The UUID of the new volume. + in: body + required: true + type: string object_count: description: | The number of objects in the backup. @@ -1267,6 +1279,12 @@ os-migrate_volume: in: body required: true type: object +os-migrate_volume_completion: + description: | + The ``os-migrate_volume_completion`` action. + in: body + required: true + type: object os-reset_status: description: | The ``os-reset_status`` action. diff --git a/api-ref/source/v2/samples/volume-os-migrate_volume_completion-request.json b/api-ref/source/v2/samples/volume-os-migrate_volume_completion-request.json new file mode 100644 index 00000000000..e938453f167 --- /dev/null +++ b/api-ref/source/v2/samples/volume-os-migrate_volume_completion-request.json @@ -0,0 +1,6 @@ +{ + "os-migrate_volume_completion": { + "new_volume": "2b955850-f177-45f7-9f49-ecb2c256d161", + "error": false, + } +} diff --git a/api-ref/source/v2/volumes-v2-volumes-actions.inc b/api-ref/source/v2/volumes-v2-volumes-actions.inc index b8f87b37c93..86644f457bc 100644 --- a/api-ref/source/v2/volumes-v2-volumes-actions.inc +++ b/api-ref/source/v2/volumes-v2-volumes-actions.inc @@ -483,6 +483,56 @@ Request Example :language: javascript +Complete migration of a volume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action + +Specify the ``os-migrate_volume_completion`` action in the request body. + +Complete the migration of a volume, updating the new volume in the DB, +returning the ``status`` of the new volume to that of the original volume +and finally deleting the original volume. + +**Preconditions** + +* Both the original and new volume ``migration_status`` must be ``None`` or + both must be set to a non ``None`` value. +* Additionally when set the new volume ``migration_status`` must take the + form of ``target:VOLUME_UUID`` where VOLUME_UUID is the original volume UUID. + +**Asynchronous Postconditions** + +On success, the volume ``status`` will return to its original status of +``available`` or ``in-use`` and the ``migration_status`` will be ``success``. +On failure, the ``migration_status`` will be ``error``. + +Response codes +-------------- + +.. rest_status_code:: success ../status.yaml + + - 202 + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - volume_id: volume_id_path + - project_id: project_id_path + - os-migrate_volume_completion: os-migrate_volume_completion + - new_volume: new_volume + - error: migration_completion_error + +Request Example +--------------- + +.. literalinclude:: ./samples/volume-os-migrate_volume_completion-request.json + :language: javascript + + Force delete volume ~~~~~~~~~~~~~~~~~~~ diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index d1ddb738f0e..a10da9e6c57 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -1773,6 +1773,12 @@ migrate_lock_volume: in: body required: false type: boolean +migration_completion_error: + description: | + Used to indicate if an error has occured elsewhere that requires clean up. + in: body + required: false + type: boolean # NOTE(mriedem): We can update the migration_policy retype note about encrypted # in-use volumes not being supported once # https://bugzilla.redhat.com/show_bug.cgi?id=760547 is fixed. @@ -1944,6 +1950,12 @@ new_type: in: body required: true type: string +new_volume: + description: | + The UUID of the new volume. + in: body + required: true + type: string no_snapshots: description: | Transfer volume without snapshots. Defaults to False if not specified. @@ -2024,6 +2036,12 @@ os-migrate_volume: in: body required: true type: object +os-migrate_volume_completion: + description: | + The ``os-migrate_volume_completion`` action. + in: body + required: true + type: object os-reserve: description: | The ``os-reserve`` action. diff --git a/api-ref/source/v3/samples/volume-os-migrate_volume_completion-request.json b/api-ref/source/v3/samples/volume-os-migrate_volume_completion-request.json new file mode 100644 index 00000000000..e938453f167 --- /dev/null +++ b/api-ref/source/v3/samples/volume-os-migrate_volume_completion-request.json @@ -0,0 +1,6 @@ +{ + "os-migrate_volume_completion": { + "new_volume": "2b955850-f177-45f7-9f49-ecb2c256d161", + "error": false, + } +} diff --git a/api-ref/source/v3/volumes-v3-volumes-actions.inc b/api-ref/source/v3/volumes-v3-volumes-actions.inc index edc66e4c49e..85c1af5418e 100644 --- a/api-ref/source/v3/volumes-v3-volumes-actions.inc +++ b/api-ref/source/v3/volumes-v3-volumes-actions.inc @@ -546,6 +546,56 @@ Request Example :language: javascript +Complete migration of a volume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action + +Specify the ``os-migrate_volume_completion`` action in the request body. + +Complete the migration of a volume, updating the new volume in the DB, +returning the ``status`` of the new volume to that of the original volume +and finally deleting the original volume. + +**Preconditions** + +* Both the original and new volume ``migration_status`` must be ``None`` or + both must be set to a non ``None`` value. +* Additionally when set the new volume ``migration_status`` must take the + form of ``target:VOLUME_UUID`` where VOLUME_UUID is the original volume UUID. + +**Asynchronous Postconditions** + +On success, the volume ``status`` will return to its original status of +``available`` or ``in-use`` and the ``migration_status`` will be ``success``. +On failure, the ``migration_status`` will be ``error``. + +Response codes +-------------- + +.. rest_status_code:: success ../status.yaml + + - 202 + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - volume_id: volume_id_path + - project_id: project_id_path + - os-migrate_volume_completion: os-migrate_volume_completion + - new_volume: new_volume + - error: migration_completion_error + +Request Example +--------------- + +.. literalinclude:: ./samples/volume-os-migrate_volume_completion-request.json + :language: javascript + + Force delete a volume ~~~~~~~~~~~~~~~~~~~~~