cinder/api-ref/source/v2/volumes-v2-volumes-actions.inc
Sofia Enriquez 09ad89b7ee Doc note warning about retyping unencrypted/encrypted volume
As suggested in 662b8210aa and
discussed at Victoria PTG[1] it would be nice to have a notes
warning users to don’t try this.

[1] https://wiki.openstack.org/wiki/CinderVictoriaPTGSummary#Sizing_encrypted_volumes

Change-Id: I3fd514126dbdf56d4d4d8e423e98e462238c683f
Partial-Bug: #1687880
2020-08-06 18:13:24 +00:00

617 lines
13 KiB
ReStructuredText

.. -*- rst -*-
Volume actions (volumes, action)
================================
Extends the size of, resets statuses for, sets image metadata for,
and removes image metadata from a volume. Attaches a volume to a
server, detaches a volume from a server, and removes a volume from
Block Storage management without actually removing the back-end
storage object associated with it.
Extend volume size
~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Extends the size of a volume to a requested size, in gibibytes (GiB). Specify
the ``os-extend`` action in the request body.
Preconditions
- Volume status must be ``available``.
- Sufficient amount of storage must exist to extend the volume.
- The user quota must have sufficient volume storage.
Troubleshooting
- An ``error_extending`` volume status indicates that the request
failed. Ensure that you meet the preconditions and retry the
request. If the request fails again, investigate the storage back
end.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- os-extend: os-extend
- new_size: new_size
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-extend-request.json
:language: javascript
Reset volume statuses
~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Administrator only. Resets the status, attach status, and migration status for
a volume. Specify the ``os-reset_status`` action in the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- status: status_3
- migration_status: migration_status
- os-reset_status: os-reset_status
- attach_status: attach_status
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-status-reset-request.json
:language: javascript
Set image metadata for volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Sets the image metadata for a volume. Specify the ``os-set_image_metadata``
action in the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
Request
-------
.. rest_parameters:: parameters.yaml
- os-set_image_metadata: os-set_image_metadata
- metadata: metadata
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-image-metadata-set-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- metadata: metadata_8
Response Example
----------------
.. literalinclude:: ./samples/volume-image-metadata-update-response.json
:language: javascript
Remove image metadata from volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Removes image metadata, by key, from a volume. Specify the
``os-unset_image_metadata`` action in the request body and the ``key`` for the
metadata key and value pair that you want to remove.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
Request
-------
.. rest_parameters:: parameters.yaml
- os-unset_image_metadata: os-unset_image_metadata
- key: key
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-image-metadata-unset-request.json
:language: javascript
Show image metadata for volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Shows image metadata for a volume.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-show_image_metadata: os-show_image_metadata
Request Example
---------------
.. literalinclude:: ./samples/image-metadata-show-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- metadata: metadata_8
Response Example
----------------
.. literalinclude:: ./samples/image-metadata-show-response.json
:language: javascript
Attach volume to server
~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Attaches a volume to a server. Specify the ``os-attach`` action in the request
body.
Preconditions
- Volume status must be ``available``.
- You should set ``instance_uuid`` or ``host_name``.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- instance_uuid: instance_uuid
- mountpoint: mountpoint
- host_name: host_name
- os-attach: os-attach
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-attach-request.json
:language: javascript
Detach volume from a server
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Detaches a volume from a server. Specify the ``os-detach`` action in the
request body.
Preconditions
- Volume status must be ``in-use``.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- attachment_id: attachment_id
- os-detach: os-detach
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-detach-request.json
:language: javascript
Unmanage volume
~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Removes a volume from Block Storage management without removing the back-end
storage object that is associated with it. Specify the ``os-unmanage`` action
in the request body.
Preconditions
- Volume status must be ``available``.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- os-unmanage: os-unmanage
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-unmanage-request.json
:language: javascript
Force detach volume
~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Forces a volume to detach. Specify the ``os-force_detach`` action in the
request body.
Rolls back an unsuccessful detach operation after you disconnect
the volume.
Policy defaults enable only users with the administrative role to
perform this operation. Cloud providers can change these permissions
through the ``volume_extension:volume_admin_actions:force_detach`` rule in
the policy configuration file.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- connector: connector
- attachment_id: attachment_id
- os-force_detach: os-force_detach
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-force-detach-request.json
:language: javascript
Retype volume
~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Change type of existing volume. Specify the ``os-retype`` action in the request
body.
Change the volume type of existing volume, Cinder may migrate the volume to
proper volume host according to the new volume type.
Retyping an *in-use* volume from a multiattach-capable type to a
non-multiattach-capable type, or vice-versa, is not supported. It is generally
not recommended to retype 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 or the owner of
the volume to perform this operation. Cloud providers can change these
permissions through the policy configuration file.
Retyping an unencrypted volume to the same size encrypted volume will most
likely fail. Even though the volume is the same size as the source volume, the
encrypted volume needs to store additional encryption information overhead.
This results in the new volume not being large enough to hold all data.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- new_type: new_type
- migration_policy: migration_policy
- os-retype: os-retype
- volume_id: volume_id_path
- project_id: project_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-os-retype-request.json
: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 configuration 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
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
~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Attempts force-delete of volume, regardless of state. Specify the
``os-force_delete`` action in the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- os-force_delete: os-force_delete
- project_id: project_id_path
- volume_id: volume_id_path
Request Example
---------------
.. literalinclude:: ./samples/volume-force-delete-request.json
:language: javascript
Update volume bootable status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action
Update the bootable status for a volume, mark it as a bootable volume. Specify
the ``os-set_bootable`` action in the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-set_bootable: os-set_bootable
- bootable: bootable
Request Example
---------------
.. literalinclude:: ./samples/volume-bootable-status-update-request.json
:language: javascript