7.5. Performing actions on volumes¶

7.5.1.1. Examples¶

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.

# 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

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

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

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

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

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

Revert a detached volume to its snapshot. The volume status must be available.

Available since API microversion 3.40. Specify the microversion in the request, for example, OpenStack-API-Version: volumes 3.59.

# curl -ks -H 'Content-Type: application/json' -H 'OpenStack-API-Version: volumes 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

7.5.2.1. Status codes¶

7.5.2.2. Examples¶

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
  }
}

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
  }
}