Perform Actions on Volumes

POST/v3/{project_id}/volumes/{volume_id}/action

Several volume operations share this endpoint. The action key in the body selects what happens; only one action per request.

info

Source: volume-actions

Request

Parameters

project_idstringrequiredpath

The UUID of the project.

volume_idstringrequiredpath

The UUID of the volume.

os-extendobjectrequiredbody

Extend the volume.

1 field

new_sizeintegerrequiredbody

New size in GiB. Must be larger than the current size.

os-attachobjectrequiredbody

Attach an available volume to a VM.

3 fields

instance_uuidstringrequiredbody

UUID of the target VM. Either this or host_name is

mountpointstringrequiredbody

Device name such as /dev/vdb.

host_namestringrequiredbody

Target host instead of a VM. Either this or instance_uuid is

os-detachobjectrequiredbody

Detach an in-use volume.

1 field

attachment_idstringrequiredbody

Attachment ID from the volume details.

os-retypeobjectrequiredbody

Change the volume type, which moves the volume to the matching storage policy.

1 field

new_typestringrequiredbody

Name or ID of the target volume type.

os-volume_upload_imageobjectrequiredbody

Create an image from the volume. QCOW2 is

2 fields

image_namestringrequiredbody

Name of the resulting image.

disk_formatstringrequiredbody

qcow2.

revertobjectrequiredbody

Revert the volume to a snapshot. Requires microversion 3.40 or later, sent in the OpenStack-API-Version header.

1 field

snapshot_idstringrequiredbody

UUID of the snapshot to revert to.

Sample Request — extend

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
-d '{
  "os-extend": {
    "new_size": 20
  }
}' https://api.vietnix.cloud:8776/v3/{project_id}/volumes/{volume_id}/action

Sample Request — attach

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://api.vietnix.cloud:8776/v3/{project_id}/volumes/{volume_id}/action

Sample Request — detach

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
-d '{
  "os-detach": {
    "attachment_id": "2b04f3a1-b16c-4c13-aa7f-d1d7f7934a12"
  }
}' https://api.vietnix.cloud:8776/v3/{project_id}/volumes/{volume_id}/action

Sample Request — create an image from the volume

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://api.vietnix.cloud:8776/v3/{project_id}/volumes/{volume_id}/action

Sample Request — revert to a snapshot

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://api.vietnix.cloud:8776/v3/{project_id}/volumes/{volume_id}/action

Response

Most actions return 202 Accepted with an empty body. os-volume_upload_image returns the volume object with status: uploading and the new image_id.

Response body

{
  "os-volume_upload_image": {
    "id": "de5b7dfc-e3e8-4f14-9969-98d61af40329",
    "status": "uploading",
    "image_id": "6b84c6e2-494e-426c-8138-86094a6c784c",
    "image_name": "vol3_image",
    "disk_format": "qcow2",
    "container_format": "bare",
    "size": 3
  }
}

Status Code

Success

Status Code	Description
200 - OK	The action completed and returned a body, as with os-volume_upload_image.
202 - Accepted	The action was accepted and is being processed.

Error

Status Code	Description
400 - Bad Request	The action is invalid, or a precondition failed, for example extending to a smaller size.
401 - Unauthorized	User must authenticate before making a request.
403 - Forbidden	Policy does not allow current user to do this operation.
404 - Not Found	The volume or the snapshot does not exist.
409 - Conflict	The volume status does not allow this action.
413 - Request Entity Too Large	The request exceeds the project quota, for example the volume gigabytes quota.

warning

Extending changes the size of the block device, not the filesystem. Grow the partition and the filesystem inside the guest afterwards, otherwise the extra space stays unused.

note

Extend requires the volume to be available before microversion 3.42. On newer microversions, an attached volume may be extendable while in-use, depending on policy and backend support. An error_extending status means the request failed; check quota and backend capacity before retrying.