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

List volumes

Update volume