Performing actions on volumes
POST /v3/{project_id}/volumes/{volume_id}/action
The request parameters depend on the action. For the list of parameters, follow the source link below.
Source: https://docs.openstack.org/api-ref/block-storage/v3/index.html#volume-actions-volumes-action
Request
Example 1
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 beavailable
. Starting with microversion3.42
, attached volumes with statusin-use
may be able to be extended depending on policy and backend volume and compute driver constraints in the cloud. Note thatreserved
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 theGET /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.
# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d ' { "os-extend": { "new_size": 3 } }' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329/action
Example 2
Attach an available
volume to a VM. Specify the os-attach
action in the request body. Also specify either instance_uuid
or host_name
.
# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d ' { "os-attach": { "instance_uuid": "e1ae6f7e-c35d-4656-a4fd-2371f9a791d4", "mountpoint": "/dev/vdb" } }' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329/action
Example 3
Detach an in-use
volume from a VM. Specify the os-detach
action in the request body. You can find out the attachment ID in volume details.
# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d ' { "os-detach": { "attachment_id": "2b04f3a1-b16c-4c13-aa7f-d1d7f7934a12" } }' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329/actio
Example 4
Change volume storage policy (“type” in OpenStack terms). Specify the os-retype
action in the request body.
Cinder may migrate the volume to proper volume host according to the new volume type.
Policy defaults enable only users with the administrative role or the owner of
the volume to perform this operation. These permissions are controlled by the policy.json
file.
# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d ' { "os-retype": { "new_type": "default" } }' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329/action
Example 5
Create an image from a volume. QCOW2 format is required.
# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d ' { "os-volume_upload_image": { "image_name": "vol3_image", "disk_format": "qcow2" } }' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329/action
Example 6
Create an image from a volume snapshot. This custom API call is only supported in Virtuozzo Hybrid Infrastructure.
# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d ' { "os-volume_upload_image": { "image_name": "vol4_image", "disk_format": "qcow2", "snapshot_id": "ca4e9232-96d3-41a6-ac28-ca3471a05b47" } }' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329/action
Example 7
Revert a volume to its snapshot. Reverting to a snapshot is supported for detached volumes with status available
or volumes with status in-use
if they are attached to stopped VMs.
Available since API microversion 3.40
. Specify the microversion in the request, for example, OpenStack-API-Version: volume 3.59
.
# curl -ks -H 'Content-Type: application/json' -H 'OpenStack-API-Version: volume 3.59' \ -H 'X-Auth-Token: gAAAAA<...>' -d ' { "revert": { "snapshot_id": "ca4e9232-96d3-41a6-ac28-ca3471a05b47" } }' https://<node_IP_addr>:8776/v3/f5d834d636c642c7bfe8af86139c6f26/volumes/de5b7dfc-e3e8-4f14-9969-98d61af40329/action
Response
Status codes
Success
Code | Reason |
---|---|
202 - Accepted
|
Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request. |
Example 1
Most requests only return the response code 202. Two exceptions follow.
Create an image from a volume:
{ "os-volume_upload_image": { "status": "uploading", "container_format": "bare", "image_name": "vol3_image", "visibility": "shared", "updated_at": "2020-03-11T12:48:21.462203", "image_id": "6b84c6e2-494e-426c-8138-86094a6c784c", "display_description": "Volume 2", "id": "de5b7dfc-e3e8-4f14-9969-98d61af40329", "size": 3, "disk_format": "qcow2", "volume_type": { "name": "default", "qos_specs_id": null, "deleted": false, "created_at": "2020-01-28T12:59:27.098490", "updated_at": null, "extra_specs": { "vz:encoding": "", "vz:volume_format": "qcow2", "volume_backend_name": "vstorage", "vz:failure-domain": "host", "vz:tier": "0", "vz:replicas": "1" }, "is_public": true, "deleted_at": null, "id": "f6ab4526-2eb4-4a2d-a6bb-e527f8263304", "description": null }, "protected": false } }
Example 2
Create an image from a snapshot:
{ "os-volume_upload_image": { "status": "uploading", "container_format": "bare", "image_name": "vol4_image", "visibility": "shared", "updated_at": "2020-03-11T15:15:40.936836", "image_id": "cb80ce16-683a-41cc-a878-02b75ba2e90f", "display_description": "Volume 2", "id": "de5b7dfc-e3e8-4f14-9969-98d61af40329", "size": 1, "disk_format": "qcow2", "volume_type": { "name": "policy1", "qos_specs_id": null, "deleted": false, "created_at": "2020-01-31T12:14:46.143657", "updated_at": null, "extra_specs": { "volume_backend_name": "vstorage", "vz:failure-domain": "disk", "vz:tier": "0", "vz:replicas": "2", "vz:encoding": "" }, "is_public": true, "deleted_at": null, "id": "e90a828e-2b81-43e1-ab14-2d22ab30d175", "description": null }, "protected": false } }