Show volume details

Overview

Shows information about a specified volume.

Classification

  • Show

API Operation Object

  • volumes

Synchronous / Asynchronous

  • synchronous

Request

HTTP Request Method

  • GET

HTTP Request Path

{api_endpoint}/v2/{tenant_id}/volumes/{volume_id}

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)

The tenant ID

required

-

Terminate

400

volume_id

URL

UUID(2)

ID of the volume to be examined

required

-

Terminate

404

token_id

Header

String(token_id)

Keystone admin token

required

-

Terminate

401

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

404

Volume that is specified do not exist

HTTP Response Body

Format

{
    "volume": {
        "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>",
        "created_at": "<created_at>",
        "description": "<description>",
        "name": "<display_name>",
        "id": "<volume_id>",
        "metadata": <metadata>,
        "size": <volume_size>,
        "snapshot_id": "<snapshot_id>",
        "status": "<status>",
        "volume_image_metadata": {
            "kernel_id": "<kernel_id>",
            "container_format": "<container_format>",
            "min_ram": "<minimum_ram_size>",
            "ramdisk_id": "<ramdisk_id>",
            "disk_format": "<disk_format>",
            "image_name": "<image_name>",
            "image_id": "<image_id>",
            "checksum": "<checksum>",
            "min_disk": "<minimum_disk_size>",
            "size": "<size>"
        },
        "volume_type": "<volume_type_name>",
        "bootable": "<bootable_state>",
        "encrypted": <encryption_state>,
        "description": "<description>",
        "name": "<display_name>",
        "os-vol-tenant-attr:tenant_id": "<tenant_id>",
        "os-vol-host-attr:host": "<host_name>",
        "source_volid": <source_volume_id>,
        "os-vol-mig-status-attr:name_id": null,
        "os-vol-mig-status-attr:migstat": null,
        "user_id": "<user_id>"
    }
}

* 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

availability_zone

availability_zone or null

availability zone name

created_at

time/date

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

description

String(0-255characters) or null

volume description

display_name

String(0-256characters) or null

volume name

volume_id

UUID

volume ID

metadata

Associative array of JSON.

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

volume metadata

volume_size

int

volume size

snapshot

UUID or null

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

status

String

volume state

kernel_id

UUID

kernel ID

container_format

String (ami, ari, aki, bare, ovf, ova)

Format of the container

minimum_ram_size

Integer

Amount of ram (in MB) required to boot image

ramdisk_id

UUID

ramdisk ID

disk_format

String (ami, ari, aki, vhd, vmdk, raw, qcow2, vdi)

Format of the disk

image_name

String(1-255characters)

Descriptive name for the image

image_id

UUID

An identifier for the image

checksum

MD5

md5 hash of image contents

minimum_disk_size

Integer

Amount of disk space (in GB) required to boot image

size

Integer

Size of image file in bytes

volume_type_name

String or null

type of the source volume

bootable state

true or false

whether bootable or not

encryption_state

true or false

encryption state

host_name

String

host name

volume_URL

URL

URL of the created volume

bookmark_URL

URL

bookmark URL

tenant_id

UUID(3)

tenant ID

source_volume_id

UUID

UUID for the source volume

user_id

String(1-255characters)

instance owner

Sample API Request and Response

Sample API Request

Request URI

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

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

{
    "volume": {
        "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>",
        "created_at": "<created_at>",
        "description": "<description>",
        "name": "<display_name>",
        "id": "<volume_id>",
        "metadata": <metadata>,
        "size": <volume_size>,
        "snapshot_id": "<snapshot_id>",
        "status": "<status>",
        "volume_image_metadata": {
            "kernel_id": "<kernel_id>",
            "container_format": "<container_format>",
            "min_ram": "<minimum_ram_size>",
            "ramdisk_id": "<ramdisk_id>",
            "disk_format": "<disk_format>",
            "image_name": "<image_name>",
            "image_id": "<image_id>",
            "checksum": "<checksum>",
            "min_disk": "<minimum_disk_size>",
            "size": "<size>"
        },
        "volume_type": "<volume_type_name>",
        "bootable": "<bootable_state>",
        "encrypted": <encryption_state>,
        "description": "<description>",
        "name": "<display_name>",
        "os-vol-tenant-attr:tenant_id": "<tenant_id>",
        "os-vol-host-attr:host": "<host_name>",
        "source_volid": <source_volume_id>,
        "os-vol-mig-status-attr:name_id": null,
        "os-vol-mig-status-attr:migstat": null,
        "user_id": "<user_id>"
    }
}

Execution Example

HTTP Request

GET /v2/ecf9a3818cfa4bfb9fcee4c73587f15b/volumes/fb47fa3a-e263-4a7a-8d83-8e3cafb42261 HTTP/1.1
Host: 192.168.11.67:8776
X-Auth-Project-Id: demo
Accept-Encoding: gzip, deflate, compress
Accept: application/json
X-Auth-Token: 2f6bd1208d0b43df80fad9b1389d61fe
User-Agent: python-cinderclient

HTTP Response

HTTP/1.1 200 OK
X-Compute-Request-Id: req-d7a81abd-9c05-42a9-8cef-fd311af0fd73
Content-Type: application/json
Content-Length: 859
X-Openstack-Request-Id: req-d7a81abd-9c05-42a9-8cef-fd311af0fd73
Date: Wed, 21 May 2014 10:31:14 GMT

{"volume": {"status": "available", "user_id": "6a9d20967b0e4d93b96b1e480b517b92", "attachments": [], "links": [{"href": "http://192.168.11.67:8776/v2/ecf9a3818cfa4bfb9fcee4c73587f15b/volumes/fb47fa3a-e263-4a7a-8d83-8e3cafb42261", "rel": "self"}, {"href": "http://192.168.11.67:8776/ecf9a3818cfa4bfb9fcee4c73587f15b/volumes/fb47fa3a-e263-4a7a-8d83-8e3cafb42261", "rel": "bookmark"}], "availability_zone": "nova", "bootable": "false", "encrypted": false, "created_at": "2014-05-21T09:48:20.000000", "description": null, "os-vol-tenant-attr:tenant_id": "ecf9a3818cfa4bfb9fcee4c73587f15b", "volume_type": null, "name": null, "os-vol-host-attr:host": "OpenStack-Dev", "source_volid": null, "snapshot_id": null, "os-vol-mig-status-attr:name_id": null, "metadata": {}, "id": "fb47fa3a-e263-4a7a-8d83-8e3cafb42261", "os-vol-mig-status-attr:migstat": null, "size": 1}}

Error Execution Example

HTTP Request

GET /v2/cb8aa2a2c7244af5aab1fa7881ba7f4/volumes/84b8be0b-840d-479a-8b87-4da58e48df00 HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:8776
X-Auth-Token: ff2e687208974dff83e05693ac8ac723
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-14899a99-ec88-4a68-9555-4cb454ddf0ca
X-Openstack-Request-Id: req-14899a99-ec88-4a68-9555-4cb454ddf0ca
Date: Thu, 15 Oct 2015 06:51:17 GMT

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