openstack/cinder
Code Issues Proposed changes
712cf414f9
cinder/api-ref/source/v3/volumes-v3-volumes-actions.inc
Konrad Gube 2a1a0bc3e2 Add the os-extend_volume_completion volume action 
Split off the finalization part of the volume manager's
extend_volume method and make it externally callable as the new
os-extend_volume_completion admin volume action.

This is the first part of a feature that will allow volume drivers
to rely on feedback from Nova when extending attached volumes,
allowing e.g. NFS-based drivers to support online extend.

See the linked blueprint for details.

Implements: bp extend-volume-completion-action
Change-Id: I4aaa5da1ad67a948102c498483de318bd245d86b
2024-02-16 18:14:33 +01:00

1121 lines
25 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 a volume size
~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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
- Prior to microversion ``3.42`` the volume status must be ``available``.
Starting with microversion ``3.42``, attached volumes with status ``in-use``
may be able to be extended depending on policy and backend volume and
compute driver constraints in the cloud. Note that ``reserved`` is not a
valid state for extend.
- Sufficient amount of storage must exist to extend the volume.
- The user quota must have sufficient volume storage.
Postconditions
- If the request is processed successfully, the volume status will change to
``extending`` while the volume size is being extended.
- Upon successful completion of the extend operation, the volume status will
go back to its original value.
- Starting with microversion ``3.42``, when extending the size of an attached
volume, the Block Storage service will notify the Compute service that an
attached volume has been extended. The Compute service will asynchronously
process the volume size change for the related server instance. This can be
monitored using the ``GET /servers/{server_id}/os-instance-actions`` API in
the Compute service.
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
- project_id: project_id_path
- volume_id: volume_id_path
- os-extend: os-extend
- new_size: new_size
Request Example
---------------
.. literalinclude:: ./samples/volume-extend-request.json
:language: javascript
Complete extending a volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Specify the ``os-extend_volume_completion`` action in the request body.
Complete extending an attached volume that has been left in status
``extending`` after notifying the compute agent.
Depending on the value of the ``error`` parameter, the extend operation
will be either rolled back or finalized.
**Preconditions**
* The volume must have the status ``extending``.
* The volume's admin metadata must contain a set of keys indicating that
Cinder was waiting for external feedback on the success of the operation.
**Asynchronous Postconditions**
If the ``error`` parameter is ``false`` or missing, and the extend operation
was successfully finalized, the volume status will be ``in-use``.
Otherwise, the volume status will be ``error_extending``.
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-extend_volume_completion: os-extend_volume_completion
- error: extend_completion_error
Request Example
---------------
.. literalinclude:: ./samples/volume-os-extend_volume_completion-request.json
:language: javascript
Reset a volume's statuses
~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Administrator only. Resets the status, attach status, revert to snapshot,
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
- project_id: project_id_path
- volume_id: volume_id_path
- os-reset_status: os-reset_status
- status: status_vol
- migration_status: migration_status
- attach_status: attach_status
Request Example
---------------
.. literalinclude:: ./samples/volume-status-reset-request.json
:language: javascript
Revert volume to snapshot
~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Revert a volume to its latest snapshot, this API only support reverting a
detached volume, and the volume status must be ``available``.
Available since API microversion ``3.40``.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- revert: revert
- snapshot_id: snapshot_id_revert
Request Example
---------------
.. literalinclude:: ./samples/volume-revert-to-snapshot-request.json
:language: javascript
Set image metadata for a volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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
- project_id: project_id_path
- volume_id: volume_id_path
- os-set_image_metadata: os-set_image_metadata
- metadata: metadata_image
Request Example
---------------
.. literalinclude:: ./samples/volume-image-metadata-set-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- metadata: metadata_image
Response Example
----------------
.. literalinclude:: ./samples/volume-image-metadata-update-response.json
:language: javascript
Remove image metadata from a volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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
- project_id: project_id_path
- volume_id: volume_id_path
- os-unset_image_metadata: os-unset_image_metadata
- key: key
Request Example
---------------
.. literalinclude:: ./samples/volume-image-metadata-unset-request.json
:language: javascript
Show image metadata for a volume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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_image
Response Example
----------------
.. literalinclude:: ./samples/image-metadata-show-response.json
:language: javascript
Attach volume to a server
~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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
- project_id: project_id_path
- volume_id: volume_id_path
- os-attach: os-attach
- instance_uuid: instance_uuid
- mountpoint: mountpoint
- host_name: host_name
Request Example
---------------
.. literalinclude:: ./samples/volume-attach-request.json
:language: javascript
Detach volume from server
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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``.
For security reasons (see bug `#2004555
<https://bugs.launchpad.net/nova/+bug/2004555>`_), regardless of the policy
defaults, the Block Storage API rejects REST API calls manually made from
users with a 409 status code if completing the request could pose a risk, which
happens if all of these happen:
- The request comes from a user
- There's an instance uuid in provided attachment or in the volume's attachment
- VM exists in Nova
- Instance has the volume attached
- Attached volume in instance is using the attachment
Calls coming from other OpenStack services (like the Compute Service) are
always accepted.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-detach: os-detach
- attachment_id: attachment_id
Request Example
---------------
.. literalinclude:: ./samples/volume-detach-request.json
:language: javascript
Unmanage a volume
~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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
- project_id: project_id_path
- volume_id: volume_id_path
- os-unmanage: os-unmanage
Request Example
---------------
.. literalinclude:: ./samples/volume-unmanage-request.json
:language: javascript
Force detach a volume
~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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.
For security reasons (see bug `#2004555
<https://bugs.launchpad.net/nova/+bug/2004555>`_), regardless of the policy
defaults, the Block Storage API rejects REST API calls manually made from
users with a 409 status code if completing the request could pose a risk, which
happens if all of these happen:
- The request comes from a user
- There's an instance uuid in provided attachment or in the volume's attachment
- VM exists in Nova
- Instance has the volume attached
- Attached volume in instance is using the attachment
Calls coming from other OpenStack services (like the Compute Service) are
always accepted.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-force_detach: os-force_detach
- attachment_id: attachment_id
- connector: connector
Request Example
---------------
.. literalinclude:: ./samples/volume-force-detach-request.json
:language: javascript
Retype a volume
~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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
- project_id: project_id_path
- volume_id: volume_id_path
- os-retype: os-retype
- new_type: new_type
- migration_policy: migration_policy
Request Example
---------------
.. literalinclude:: ./samples/volume-os-retype-request.json
: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 configuration 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
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
~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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
- project_id: project_id_path
- volume_id: volume_id_path
- os-force_delete: os-force_delete
Request Example
---------------
.. literalinclude:: ./samples/volume-force-delete-request.json
:language: javascript
Update a volume's bootable status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{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_required
Request Example
---------------
.. literalinclude:: ./samples/volume-bootable-status-update-request.json
:language: javascript
Upload volume to image
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Uploads the specified volume to image service.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-volume_upload_image: os-volume_upload_image
- image_name: image_name
- force: force_upload_vol
- disk_format: disk_format_upload
- container_format: container_format_upload
- visibility: visibility_min
- protected: protected
Request Example
---------------
.. literalinclude:: ./samples/volume_actions/volume-upload-to-image-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- os-volume_upload_image: os-volume_upload_image
- status: status_vol
- image_name: image_name
- disk_format: disk_format
- container_format: container_format
- visibility: visibility_min
- protected: protected
- updated_at: updated_at
- image_id: image_id
- display_description: description_vol_req
- id: id_vol
- size: size
- volume_type: volume_type_vol
Response Example
----------------
.. literalinclude:: ./samples/volume_actions/volume-upload-to-image-response.json
:language: javascript
Reserve volume
~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Mark volume as reserved. Specify the ``os-reserve`` 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
- project_id: project_id_path
- volume_id: volume_id_path
- os-reserve: os-reserve
Request Example
---------------
.. literalinclude:: ./samples/volume-reserve-request.json
:language: javascript
Unmark volume as reserved.
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Unmark volume as reserved. Specify the ``os-unreserve`` action in
the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-unreserve: os-unreserve
Request Example
---------------
.. literalinclude:: ./samples/volume-unreserve-request.json
:language: javascript
Update volume status to detaching
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Update volume status to 'detaching'.. Specify the ``os-begin_detaching`` action
in the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-begin_detaching: os-begin_detaching
Request Example
---------------
.. literalinclude:: ./samples/volume-begin-detaching-request.json
:language: javascript
Roll back volume status to in-use
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Roll back volume status to 'in-use'. Specify the ``os-roll_detaching`` action
in the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-roll_detaching: os-roll_detaching
Request Example
---------------
.. literalinclude:: ./samples/volume-roll-detaching-request.json
:language: javascript
Terminate volume attachment
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Terminate volume attachment. Specify the ``os-terminate_connection``
action in the request body.
Preconditions
- Volume status must be ``in-use``.
For security reasons (see bug `#2004555
<https://bugs.launchpad.net/nova/+bug/2004555>`_), regardless of the policy
defaults, the Block Storage API rejects REST API calls manually made from
users with a 409 status code if completing the request could pose a risk, which
happens if all of these happen:
- The request comes from a user
- There's an instance uuid in the volume's attachment
- VM exists in Nova
- Instance has the volume attached
- Attached volume in instance is using the attachment
Calls coming from other OpenStack services (like the Compute Service) are
always accepted.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-terminate_connection: os-terminate_connection
- connector: connector_required
Request Example
---------------
.. literalinclude:: ./samples/volume-terminate-connection-request.json
:language: javascript
Initialize volume attachment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Initialize volume attachment. Specify the ``os-initialize_connection``
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-initialize_connection: os-initialize_connection
- connector: connector_required
Request Example
---------------
.. literalinclude:: ./samples/volume-initialize-connection-request.json
:language: javascript
Updates volume read-only access-mode flag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Enables or disables update of volume to read-only access mode.
Specify the ``os-update_readonly_flag`` action in the request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- os-update_readonly_flag: os-update_readonly_flag
- readonly: readonly
Request Example
---------------
.. literalinclude:: ./samples/volume-readonly-update-request.json
:language: javascript
Reimage a volume
~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action
Re-image a volume with a specific image. Specify the ``os-reimage`` action
in the request body.
A volume in ``available`` or ``error`` status can be re-imaged directly. To
re-image a volume in ``reserved`` status, you must include the
``reimage_reserved`` parameter set to ``true``.
.. note:: Image signature verification is currently unsupported when
re-imaging a volume.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- volume_id: volume_id_path
- image_id: image_id
- reimage_reserved: reimage_reserved
- os-reimage: os-reimage
Request Example
---------------
.. literalinclude:: ./samples/volume-os-reimage-request.json
:language: javascript
View Git Blame Copy Permalink