List volumes with details

Overview

Lists summary detailed information for all Block Storage volumes that the tenant who submits the request can access.

Classification

  • List

API Operation Object

  • volumes

Synchronous / Asynchronous

  • synchronous

Request

HTTP Request Method

  • GET

HTTP Request Path

{api_endpoint}/v2/{tenant_id}/volumes/detail

HTTP Request Header

Format

Accept-Encoding: gzip, deflate, compress (optional)
Accept: application/json
X-Auth-Token: <token_id>

HTTP Request Body

Format

  • none

Request Parameter

Request Parameters

name

style

format

description

required/optional

default value

action for invalid parameter

response code for invalid parameter

tenant_id

URL

UUID(3)

ID of the tenant

required

-

Terminate

400

token_id

Header

String(token_id)

Keystone admin token

required

-

Terminate

401

marker

Query

UUID

UUID of the server at which you want to set a marker.

optional

-

Terminate

400

limit

Query

int

Integer value for the limit of values to return.

optional

-

Terminate

400

page_size

Query

int

page size for result

optional

-

Terminate

400

created_at

Query

time/date

created time

optional

-

-

-

updated_at

Query

time/date

last updated time

optional

-

-

-

id

Query

UUID

volume id

optional

-

-

-

ec2_id

Query

String(1-255characters)

ec2_id is not used by juno

optional

-

-

-

user_id

Query

String(1-255characters)

volume owner

optional

-

-

-

project_id

Query

UUID(3)

project id

optional

-

-

-

host

Query

String

host name

optional

-

-

-

size

Query

int

volume size

optional

-

-

-

availability_zone

Query

availability_zone

availability zone name

optional

-

-

-

instance_uuid

Query

UUID(2)

instance ID given volume

optional

-

-

-

mountpoint

Query

device name

ex:/dev/vdb

device name

optional

-

-

-

attach_time

Query

time/date

attached time

optional

-

-

-

status

Query

String

volume state

optional

-

-

-

attach_status

Query

detached or attached

attach state

optional

-

-

-

scheduled_at

Query

time/date

scheduled time

optional

-

-

-

launched_at

Query

time/date

launched a time

optional

-

-

-

terminated_at

Query

time/date

terminated time

optional

-

-

-

display_name

Query

String(0-256characters) or null

volume name

optional

-

-

-

display_description

Query

String(0-255characters) or null

volume description

optional

-

-

-

provider_location

Query

String(1-255characters)

volume location

optional

-

-

-

provider_auth

Query

String(1-255characters)

volume provider's auth information

optional

-

-

-

snapshot_id

Query

UUID or null

(volume) snapshot ID that becomes source data of the volume.

optional

-

-

-

volume_type_id

Query

UUID

volume type id

optional

-

-

-

source_volid

Query

UUID

source volume id

optional

-

-

-

bootable

Query

true or false

whether bootable or not

optional

-

-

-

attached_host

Query

String(1-255characters)

attached host name

optional

-

-

-

provider_geometry

Query

String(1-255characters)

solidfire driver only uses

optional

-

-

-

_name_id

Query

UUID

volume id of temporary volume for migrating.

optional

-

-

-

encryption_key_id

Query

UUID

encryption id

optional

-

-

-

migration_status

Query

migrate_state

migrate state

optional

-

-

-

replication_status

Query

replication_state

replication state

optional

-

-

-

replication_extended_status

Query

String(0-255characters)

Extended state for volume replication.

optional

-

-

-

replication_driver_data

Query

String(0-255characters)

driver data for replication

optional

-

-

-

consistencygroup_id

Query

UUID

ID of a consistency group

optional

-

-

-

Response

HTTP Response Header

Format

HTTP/1.1 <response code> <message>       (ex. 200 OK)
  • <response_code>: see "HTTP Responses" section

  • <message>: message based on the response code

    • skip auto insert field such as "X-Compute-Request-Id" and "X-Openstack-Request-Id", "Content-Length", "Date"

Response Code

Response Codes

response code

condition

200

normal end

400

invalid input for tenant ID

401

unauthorized(including keystone down)

403

User who requested are not allowed to do

HTTP Response Body

Format

{
    "volumes": [{
        "attachments": [
            {
                "device": "<device_name>",
                "id": "<volume_id>",
                "server_id": "<instance_id>",
                "volume_id": "<volume_id>"
            }
        ],
        "links": [
            {
                "href": "<volume_URL>",
                "rel": "self"
            },
            {
                "href": "<bookmark_URL>",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "<availability_zone>",
        "os-vol-host-attr:host": "<host_name>",
        "encrypted": "<encryption_state>",
        "os-volume-replication:extended_status": "<replication_extended_status>",
        "replication_status": "<replication_status>",
        "snapshot_id": "<snapshot_id>",
        "id": "<volume_id>",
        "size": <volume_size>,
        "user_id": "<user_id>"
        "os-vol-tenant-attr:tenant_id": "<tenant_id>",
        "os-vol-mig-status-attr:migstat": <migration_status>,
        "metadata": <metadata>,
        "status": "<status>",
        "description": "<description>",
        "os-volume-replication:driver_data": "<replication_driver_data>",
        "source_volid": <source_volume_id>,
        "consistencygroup_id": "<consistency_group_id>",
        "os-vol-mig-status-attr:name_id": <name_id>,
        "name": "<display_name>",
        "bootable": "<bootable_state>",
        "created_at": "<created_at>",
        "volume_type": "<volume_type_name>"
    },
    <<repeat>>
    ]
}

* volume_image_metadata entity is output only when you specify the imeage_ref in volume.

Response Parameter

Response Parameters

item

format

description

device_name

device name

ex:/dev/vdb

device name

instance_id

UUID(2)

instance ID given volume

volume_id

UUID

volume ID

volume_URL

URL

URL of the created volume

bookmark_URL

URL

bookmark URL

availability_zone

availability_zone or null

availability zone name

host_name

String

host name

encryption_state

true or false

encryption state

replication_extended_status

String(0-255characters) or null

Extended state for volume replication.

replication_status

replication_state or null

Replication state

snapshot_id

UUID or null

(volume) snapshot ID that becomes source data of the volume.

volume_size

int

volume size

user_id

String(1-255characters)

instance owner

tenant_id

UUID(3)

tenant ID

migration_status

migrate_state or null

migration state

metadata

Associative array of JSON.

ex:{ "key1": "value1", "key2": "value2"}

volume metadata

status

String

volume state

description

String(0-255characters) or null

volume description

replication_driver_data

String(0-255characters) or null

driver data for replication

source_volume_id

UUID or null

volume ID

consistency_group_id

UUID or null

ID of a consistency group.

name_id

UUID or null

volume id of temporary volume for migrating.

display_name

String(0-256characters) or null

volume name

bootable state

true or false

whether bootable or not

created_at

time/date

"yyyy-mm-ddThh:mm:ss.ssssss" format

volume_type_name

String or null

type of the source volume

Sample API Request and Response

Sample API Request

Request URI

https://example.com/v2/{tenant_id}/volumes/detail

Request Header

Accept-Encoding: gzip, deflate, compress(optional)
Accept: application/json
X-Auth-Token: ajk3adjiown02

Request Body

  • none

Sample API Response

Response Header

HTTP/1.1 200 OK
  • <response_code>: see "HTTP Responses" section

  • <message>: message based on the response code

    • skip auto insert field such as "X-Compute-Request-Id" and "X-Openstack-Request-Id", "Content-Length", "Date"

Response Body

{
    "volumes": [{
        "attachments": [
            {
                "device": "<device_name>",
                "id": "<volume_id>",
                "server_id": "<instance_id>",
                "volume_id": "<volume_id>"
            }
        ],
        "links": [
            {
                "href": "<volume_URL>",
                "rel": "self"
            },
            {
                "href": "<bookmark_URL>",
                "rel": "bookmark"
            }
        ],
        "availability_zone": "<availability_zone>",
        "os-vol-host-attr:host": "<host_name>",
        "encrypted": "<encryption_state>",
        "os-volume-replication:extended_status": "<replication_extended_status>",
        "replication_status": "<replication_status>",
        "snapshot_id": "<snapshot_id>",
        "id": "<volume_id>",
        "size": <volume_size>,
        "user_id": "<user_id>"
        "os-vol-tenant-attr:tenant_id": "<tenant_id>",
        "os-vol-mig-status-attr:migstat": <migration_status>,
        "metadata": <metadata>,
        "status": "<status>",
        "description": "<description>",
        "os-volume-replication:driver_data": "<replication_driver_data>",
        "source_volid": <source_volume_id>,
        "consistencygroup_id": "<consistency_group_id>",
        "os-vol-mig-status-attr:name_id": <name_id>,
        "name": "<display_name>",
        "bootable": "<bootable_state>",
        "created_at": "<created_at>",
        "volume_type": "<volume_type_name>"
    },
    <<repeat>>
    ]
}

Execution Example

HTTP Request

GET /v2/a0b3f85088bf43c1a26eb0e0f8b0b38d/volumes/detail HTTP/1.1
User-Agent: python-cinderclient
Host: 10.0.75.111:8776
X-Auth-Token: 5574e97cb2114d8198492ceecff96485
Accept: application/json

HTTP Response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-62a6c98c-7540-421c-8b75-1af2cb254bd3
Content-Type: application/json
Content-Length: 1019
X-Openstack-Request-Id: req-62a6c98c-7540-421c-8b75-1af2cb254bd3
Date: Tue, 23 Dec 2014 12:38:34 GMT

{"volumes": [{"attachments": [], "links": [{"href": "http://10.0.75.111:8776/v2/a0b3f85088bf43c1a26eb0e0f8b0b38d/volumes/110977c2-58fc-4005-a1b6-b60c570c1138", "rel": "self"}, {"href": "http://10.0.75.111:8776/a0b3f85088bf43c1a26eb0e0f8b0b38d/volumes/110977c2-58fc-4005-a1b6-b60c570c1138", "rel": "bookmark"}], "availability_zone": "nova", "os-vol-host-attr:host": "ubuntu1404#Generic_NFS", "encrypted": false, "os-volume-replication:extended_status": null, "replication_status": "disabled", "snapshot_id": null, "id": "110977c2-58fc-4005-a1b6-b60c570c1138", "size": 1, "user_id": "e9faee7643554c01b66e9b33f22655e5", "os-vol-tenant-attr:tenant_id": "a0b3f85088bf43c1a26eb0e0f8b0b38d", "os-vol-mig-status-attr:migstat": null, "metadata": {}, "status": "creating", "description": null, "os-volume-replication:driver_data": null, "source_volid": null, "consistencygroup_id": null, "os-vol-mig-status-attr:name_id": null, "name": null, "bootable": "false", "created_at": "2014-12-23T12:37:39.000000", "volume_type": null}]}

Error Execution Example

HTTP Request

GET /v2/cb8aa2a2c7244af5aab1fa7881ba7f4/volumes/detail HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:8776
X-Auth-Token: e5b9c5a08fa3481f848792a79378251e
Content-type: application/json
Accept: application/json

HTTP Response

HTTP/1.1 400 Bad Request
Content-Length: 65
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-bdb12f48-aedf-49b0-ad3b-e823408f93a0
X-Openstack-Request-Id: req-bdb12f48-aedf-49b0-ad3b-e823408f93a0
Date: Thu, 15 Oct 2015 09:25:18 GMT

{"badRequest": {"message": "Malformed request url", "code": 400}}