From 76cc9bd02b805356ce60cd5810a93900448f03d5 Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Wed, 22 Aug 2018 20:38:22 -0400 Subject: [PATCH] api-ref: add docs for os-migrate_volume API Adds the v2 and v3 API reference documentation for the admin-only (by default) os-migrate_volume volume action API. The only major difference with the v3 API is the cluster parameter introduced in the 3.16 microversion. Change-Id: I70f6b2cc4d25ea155ce09ddeec26b995890a2db3 Partial-Bug: #1607539 --- api-ref/source/v2/parameters.yaml | 29 ++++++++ .../volume-os-migrate_volume-request.json | 5 ++ .../source/v2/volumes-v2-volumes-actions.inc | 63 +++++++++++++++++ api-ref/source/v3/parameters.yaml | 40 +++++++++++ .../volume-os-migrate_volume-request.json | 5 ++ .../source/v3/volumes-v3-volumes-actions.inc | 67 +++++++++++++++++++ 6 files changed, 209 insertions(+) create mode 100644 api-ref/source/v2/samples/volume-os-migrate_volume-request.json create mode 100644 api-ref/source/v3/samples/volume-os-migrate_volume-request.json diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 4dd0814a86d..17d9f418a2d 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -980,6 +980,29 @@ metadata_items: in: body required: true type: integer +migrate_force_host_copy: + description: | + If false (the default), rely on the volume backend driver to perform + the migration, which might be optimized. If true, or the volume driver + fails to migrate the volume itself, a generic host-based migration is + performed. + in: body + required: false + type: boolean +migrate_host: + description: | + The target host for the volume migration. Host format is ``host@backend``. + in: body + required: true + type: string +migrate_lock_volume: + description: | + If true, migrating an ``available`` volume will change its status to + ``maintenance`` preventing other operations from being performed on the + volume such as attach, detach, retype, etc. + 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. @@ -1201,6 +1224,12 @@ os-force_detach: in: body required: true type: object +os-migrate_volume: + description: | + The ``os-migrate_volume`` 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-request.json b/api-ref/source/v2/samples/volume-os-migrate_volume-request.json new file mode 100644 index 00000000000..34132a0b6e6 --- /dev/null +++ b/api-ref/source/v2/samples/volume-os-migrate_volume-request.json @@ -0,0 +1,5 @@ +{ + "os-migrate_volume": { + "host": "node1@lvm" + } +} \ No newline at end of file diff --git a/api-ref/source/v2/volumes-v2-volumes-actions.inc b/api-ref/source/v2/volumes-v2-volumes-actions.inc index 24b57938431..c37e448614e 100644 --- a/api-ref/source/v2/volumes-v2-volumes-actions.inc +++ b/api-ref/source/v2/volumes-v2-volumes-actions.inc @@ -405,6 +405,69 @@ Request Example :language: javascript +Migrate volume +~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action + +Specify the ``os-migrate_volume`` action in the request body. + +Migrates a volume to the specified host. + +It is generally not recommended to migrate an *in-use* multiattach volume if +that volume has more than one active read/write attachment. + +Policy defaults enable only users with the administrative role to perform this +operation. Cloud providers can change these permissions through the +policy.json file. + +**Preconditions** + +* The volume ``status`` must be ``available`` or ``in-use``. +* The volume ``migration_status`` must be ``None``, ``deleting``, ``error``, + or ``success``. +* The volume ``replication_status`` must be ``None``, ``disabled`` or + ``not-capable``. +* The migration must happen to another host from which the + volume currently resides. +* The volume must not be a member of a group. +* The volume must not have snapshots. + +**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``. In the case of failure, +if ``lock_volume`` was true and the volume was originally ``available`` when +it was migrated, the ``status`` will go back to ``available``. + +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: os-migrate_volume + - host: migrate_host + - force_host_copy: migrate_force_host_copy + - lock_volume: migrate_lock_volume + +Request Example +--------------- + +.. literalinclude:: ./samples/volume-os-migrate_volume-request.json + :language: javascript + + Force delete volume ~~~~~~~~~~~~~~~~~~~ diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 6e65ea1e786..7ae13561b60 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -1724,6 +1724,40 @@ metadata_9: required: false type: object min_version: 3.43 +migrate_cluster: + description: | + The target cluster for the volume migration. Cluster format is + ``cluster@backend``. Starting with microversion 3.16, either ``cluster`` + or ``host`` must be specified. If ``host`` is specified and is part of a + cluster, the cluster is used as the target for the migration. + in: body + required: false + type: string + min_version: 3.16 +migrate_force_host_copy: + description: | + If false (the default), rely on the volume backend driver to perform + the migration, which might be optimized. If true, or the volume driver + fails to migrate the volume itself, a generic host-based migration is + performed. + in: body + required: false + type: boolean +migrate_host: + description: | + The target host for the volume migration. Host format is ``host@backend``. + Required before microversion 3.16. + in: body + required: false + type: string +migrate_lock_volume: + description: | + If true, migrating an ``available`` volume will change its status to + ``maintenance`` preventing other operations from being performed on the + volume such as attach, detach, retype, etc. + 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. @@ -2010,6 +2044,12 @@ os-initialize_connection: in: body required: true type: object +os-migrate_volume: + description: | + The ``os-migrate_volume`` 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-request.json b/api-ref/source/v3/samples/volume-os-migrate_volume-request.json new file mode 100644 index 00000000000..34132a0b6e6 --- /dev/null +++ b/api-ref/source/v3/samples/volume-os-migrate_volume-request.json @@ -0,0 +1,5 @@ +{ + "os-migrate_volume": { + "host": "node1@lvm" + } +} \ No newline at end of file diff --git a/api-ref/source/v3/volumes-v3-volumes-actions.inc b/api-ref/source/v3/volumes-v3-volumes-actions.inc index cedc66bb5a7..0d9d6d6e13f 100644 --- a/api-ref/source/v3/volumes-v3-volumes-actions.inc +++ b/api-ref/source/v3/volumes-v3-volumes-actions.inc @@ -464,6 +464,73 @@ Request Example :language: javascript +Migrate a volume +~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action + +Specify the ``os-migrate_volume`` action in the request body. + +Migrates a volume to the specified host. Starting with the +`3.16 microversion`_ a cluster can be specified instead of a host. + +It is generally not recommended to migrate an *in-use* multiattach volume if +that volume has more than one active read/write attachment. + +Policy defaults enable only users with the administrative role to perform this +operation. Cloud providers can change these permissions through the +policy.json file. + +.. _3.16 microversion: https://docs.openstack.org/cinder/latest/contributor/api_microversion_history.html#id15 + +**Preconditions** + +* The volume ``status`` must be ``available`` or ``in-use``. +* The volume ``migration_status`` must be ``None``, ``deleting``, ``error``, + or ``success``. +* The volume ``replication_status`` must be ``None``, ``disabled`` or + ``not-capable``. +* The migration must happen to another host (or cluster) from which the + volume currently resides. +* The volume must not be a member of a group. +* The volume must not have snapshots. + +**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``. In the case of failure, +if ``lock_volume`` was true and the volume was originally ``available`` when +it was migrated, the ``status`` will go back to ``available``. + +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: os-migrate_volume + - host: migrate_host + - force_host_copy: migrate_force_host_copy + - lock_volume: migrate_lock_volume + - cluster: migrate_cluster + +Request Example +--------------- + +.. literalinclude:: ./samples/volume-os-migrate_volume-request.json + :language: javascript + + Force delete a volume ~~~~~~~~~~~~~~~~~~~~~