openstack/cinder
Code Issues Proposed changes
cinder/api-ref/source/v2/volumes-v2-volumes-actions.inc
Matt Riedemann 2e1d31a44a api-ref: add multiattach considerations to retype docs 
This adds some notes about two things to consider with a volume
retype operation on an in-use multiattach volume:

1. The volume API will reject a retype operation on an in-use volume
   where the volume's multiattach value would change.

2. Retyping an in-use volume that has more than one active read/write
   attachment is not recommended because on the nova side the swap
   volume operation performs a blockRebase which could potentially
   lead to data corruption.

In the future, we (nova or cinder or both) will likely need to make
some changes as to what the default attach_mode is for secondary
attachments to a multiattach volume, since today we default to read/write
if it's not specified by the caller when making the attachment.

Change-Id: Ib5a2830ea3cd37236947677225252ef42edaa347
2018-01-25 13:48:05 -05:00

437 lines
8.6 KiB
ReStructuredText
Raw Blame History

.. -*- 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.
Normal response codes: 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.
Normal response codes: 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.
Normal response codes: 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
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.
Normal response codes: 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.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-vol-image-meta: 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``.
Normal response codes: 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``.
Normal response codes: 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``.
Normal response codes: 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.
Normal response codes: 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.json file.
Normal response codes: 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
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.
Normal response codes: 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.
Normal response codes: 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
View Git Blame Copy Permalink