.. -*- 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
