Openstack Blockstorage API Ref

docs.openstack.
org
Block Storage API Reference
July 29, 2014
API v2 and extensions
OpenStack Block Storage API v2 Reference

API v2 and extensions (2014-07-29)
Copyright 2013, 2014 OpenStack Foundation All rights reserved.

This document is for software developers who develop applications by using the OpenStack Block Storage
Application Programming Interface (API).
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You
may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing
permissions and limitations under the License.
ii
July 29, 2014
Table of Contents
Preface ............................................................................................................................ 7
Intended audience .................................................................................................. 7
Additional resources ................................................................................................ 7
1. Overview ..................................................................................................................... 1
Glossary .................................................................................................................. 2
High-level task flow ................................................................................................. 3
2. General API information ............................................................................................. 4
Authentication ........................................................................................................ 4
Request and response types .................................................................................... 5
HTTP response status codes .................................................................................... 5
Limits ...................................................................................................................... 6
Date and time format ............................................................................................. 6
Faults ...................................................................................................................... 7
3. API operations .......................................................................................................... 10
Volumes ................................................................................................................ 10
Snapshots .............................................................................................................. 23
Volume types ........................................................................................................ 33
Quality of service (QoS) specifications (qos-specs) .................................................. 35
Quota sets extension (os-quota-sets) ..................................................................... 47
Limits extension (limits) ......................................................................................... 64
Backups extension ................................................................................................. 65
iii
July 29, 2014
List of Tables
2.1. Response formats ..................................................................................................... 5
2.2. Absolute limits ......................................................................................................... 6
2.3. Date time format codes ........................................................................................... 6
iv
July 29, 2014
List of Examples
2.1. Request with headers: Get volume types .................................................................. 5
2.2. Response with headers ............................................................................................. 5
2.3. DB service date and time format .............................................................................. 6
2.4. Example instanceFault response: XML ....................................................................... 7
2.5. Example fault response: JSON .................................................................................. 8
2.6. Example badRequest fault on volume size errors: XML .............................................. 8
2.7. Example badRequest fault on volume size errors: JSON ............................................. 8
2.8. Example itemNotFound fault: XML ........................................................................... 9
2.9. Example itemNotFound fault: JSON .......................................................................... 9
3.1. Create volume: JSON request ................................................................................. 11
3.2. Create volume: XML request .................................................................................. 12
3.3. Create volume: JSON response ............................................................................... 12
3.4. Create volume: XML response ................................................................................ 13
3.5. List volumes: XML response .................................................................................... 14
3.6. List volumes: JSON response ................................................................................... 14
3.7. List volumes (detailed): XML response .................................................................... 16
3.8. List volumes (detailed): JSON response ................................................................... 17
3.9. Show volume information: XML response ............................................................... 19
3.10. Show volume information: JSON response ............................................................ 19
3.11. Update volume: XML request ............................................................................... 21
3.12. Update volume: JSON request .............................................................................. 21
3.13. Update volume: XML response ............................................................................. 21
3.14. Update volume: JSON response ............................................................................ 22
3.15. Create snapshot: XML request .............................................................................. 24
3.16. Create snapshot: JSON request ............................................................................. 24
3.17. Create snapshot: XML response ............................................................................ 25
3.18. Create snapshot: JSON response ........................................................................... 25
3.19. List snapshots: XML response ................................................................................ 26
3.20. List snapshots: JSON response ............................................................................... 26
3.21. List snapshots (detailed): XML response ................................................................ 28
3.22. List snapshots (detailed): JSON response ............................................................... 28
3.23. Show snapshot information: XML response ........................................................... 30
3.24. Show snapshot information: JSON response .......................................................... 30
3.25. Update snapshot: XML request ............................................................................. 31
3.26. Update snapshot: JSON request ............................................................................ 31
3.27. Update snapshot: XML response ........................................................................... 31
3.28. Update snapshot: JSON response .......................................................................... 32
3.29. List volume types: XML response .......................................................................... 34
3.30. List volume types: JSON response ......................................................................... 34
3.31. Show volume type information: JSON response ..................................................... 35
3.32. Show volume type information: XML response ...................................................... 35
3.33. Create QoS specification: JSON request ................................................................. 37
3.34. Create QoS specification: XML request .................................................................. 37
3.35. Create QoS specification: JSON response ............................................................... 37
3.36. Create QoS specification: XML response ................................................................ 38
3.37. List QoS specs: JSON response .............................................................................. 39
3.38. List QoS specs: XML response ............................................................................... 40
3.39. Show QoS specification details: JSON response ...................................................... 41
July 29, 2014
3.40. Show QoS specification details: XML response .......................................................

3.41. Get all associations for QoS specification: XML response ........................................
3.42. Get all associations for QoS specification: JSON response .......................................
3.43. Show quotas response: JSON ................................................................................
3.44. Show quotas response: XML .................................................................................
3.45. Update quotas response: JSON .............................................................................
3.46. Show quotas response: XML .................................................................................
3.47. Update quota response: JSON ..............................................................................
3.48. Update quota response: XML ...............................................................................
3.49. Get default quotas response: JSON .......................................................................
3.50. Get default quotas response: XML ........................................................................
3.51. Show quotas for user response: JSON ...................................................................
3.52. Show quotas for user response: XML ....................................................................
3.53. Update quotas for user request: JSON ..................................................................
3.54. Update quotas for user request: XML ...................................................................
3.55. Update quotas for user response: JSON ................................................................
3.56. Show quotas for user response: XML ....................................................................
3.57. Show quota details for user response: JSON ..........................................................
3.58. Show absolute limits: JSON response ....................................................................
3.59. Show absolute limits: XML response .....................................................................
3.60. Create backup: JSON request ................................................................................
3.61. Create backup: JSON response ..............................................................................
3.62. List backups: JSON response .................................................................................
3.63. List backups (detailed): JSON response ..................................................................
3.64. Show backup details: JSON response ....................................................................
3.65. Restore backup: JSON request ..............................................................................
3.66. Restore backup: JSON response ............................................................................
vi
42
47
47
49
50
51
52
52
53
55
56
57
58
59
60
60
61
63
65
65
67
67
68
70
72
74
74
July 29, 2014
Preface
Intended audience .......................................................................................................... 7
Additional resources ........................................................................................................ 7
OpenStack Block Storage provides volume management with the OpenStack Compute
service.
This document describes the features available with the Block Storage API v2.0.
We welcome feedback, comments and bug reports at bugs.launchpad.net/Cinder.
Intended audience
This guide assists software developers who develop applications by using the Block Storage
API v2.0. It assumes the reader has a general understanding of storage and is familiar with:
ReSTful web services
HTTP/1.1 conventions
JSON and/or XML data serialization formats
Additional resources
You can download the latest API-related documents from docs.openstack.org/api/.
This API uses standard HTTP 1.1 response codes as documented at: www.w3.org/Protocols/
rfc2616/rfc2616-sec10.html.
July 29, 2014
1. Overview
Glossary .......................................................................................................................... 2
High-level task flow ......................................................................................................... 3
OpenStack Block Storage is a block-level storage solution that enables you to:
Mount drives to OpenStack Cloud Servers to scale storage without paying for more
compute resources.
Use high performance storage to serve database or I/O-intensive applications.
You interact with Block Storage programmatically through the Block Storage API as
described in this guide.
Note
OpenStack Block Storage is an add-on feature to OpenStack Nova Compute
in Folsom versions and earlier.
Block Storage is multi-tenant rather than dedicated.
Block Storage allows you to create snapshots that you can save, list, and
restore.
Block Storage allows you to create backups of your volumes to Object
Storage for archival and disaster recovery purposes. These backups can be
subsequently restored to the same volume or new volumes.
July 29, 2014
Glossary
To use the Block Storage API effectively, you must understand several key concepts:
Volume
A detachable block storage device. You can think of it as a USB hard drive. It can only be
attached to one instance at a time.
Volume type
A type of a block storage volume. You can define whatever types work best for you, such
as SATA, SCSCI, SSD, etc. These can be customized or defined by the OpenStack admin.
You can also define extra_specs associated with your volume types. For instance,
you could have a VolumeType=SATA, with extra_specs (RPM=10000, RAID-Level=5) .
Extra_specs are defined and customized by the admin.
Snapshot
A point in time copy of the data contained in a volume.
Instance
A virtual machine (VM) that runs inside the cloud.
Backup
A full copy of a volume stored in an external service. The service can be configured. The
only supported service for now is Object Storage. A backup can subsequently be restored
from the external service to either the same volume that the backup was originally taken
from, or to a new volume.
July 29, 2014
High-level task flow

Procedure1.1.To create and attach a volume
1.
You create a volume.

For example, you might create a 30 GB volume called vol1, as follows:
$ cinder create --display-name vol1 30
The command returns the 521752a6-acf6-4b2d-bc7a-119f9148cd8c volume

ID.
2.
You attach that volume to a virtual machine (VM) with the

616fb98f-46ca-475e-917e-2563e5a8cd19 ID, as follows:
For example:
$ nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6acf6-4b2d-bc7a-119f9148cd8c /dev/vdb
July 29, 2014
2. General API information

Authentication ................................................................................................................
Request and response types ............................................................................................
HTTP response status codes ............................................................................................
Limits ..............................................................................................................................
Date and time format .....................................................................................................
Faults ..............................................................................................................................
4
5
5
6
6
7
The Block Storage API is implemented using a ReSTful web service interface. Like other
OpenStack projects, Block Storage shares a common token-based authentication system
that allows access between products and services.
Note
All requests to authenticate against and operate the service are performed
using SSL over HTTP (HTTPS) on TCP port 443.
Authentication
You can use cURL to try the authentication process in two steps: get a token, and send the
token to a service.
1. Get an authentication token by providing your user name and either your API key or
your password. Here are examples of both approaches:
You can request a token by providing your user name and your password.
$ curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":
{"passwordCredentials":{"username": "joecool", "password":"coolword"},
"tenantId":"5"}}' -H 'Content-type: application/json'
Successful authentication returns a token which you can use as evidence that your
identity has already been authenticated. To use the token, pass it to other services as an
X-Auth-Token header.
Authentication also returns a service catalog, listing the endpoints you can use for Cloud
services.
2. Use the authentication token to send a GET to a service you would like to use.
Authentication tokens are typically valid for 24 hours. Applications should be designed to
re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.
Important
If you programmatically parse an authentication response, be aware that
service names are stable for the life of the particular service and can be used as
keys. You should also be aware that a user's service catalog can include multiple
uniquely-named services that perform similar functions.
4
July 29, 2014
Request and response types

The Block Storage API supports both the JSON and XML data serialization formats. The
request format is specified using the Content-Type header and is required for calls that
have a request body. The response format can be specified in requests either by using the
Accept header or by adding an .xml or .json extension to the request URI. Note that
it is possible for a response to be serialized using a format different from the request. If no
response format is specified, JSON is the default. If conflicting formats are specified using
both an Accept header and a query extension, the query extension takes precedence.
Table2.1.Response formats
Format
Accept Header
Query Extension
Default
JSON
application/json
.json
Yes
XML
application/xml
.xml
No
In the request example below, notice that Content-Type is set to application/json,

but application/xml is requested via the Accept header:
Example2.1.Request with headers: Get volume types

GET /v2/441446/types HTTP/1.1
Host: dfw.blockstorage.api.openstackcloud.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Accept: application/xml
An XML response format is returned:
Example2.2.Response with headers

HTTP/1.1 200 OK
Date: Fri, 20 Jul 2012 20:32:13 GMT
Content-Length: 187
Content-Type: application/xml
X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<?xml version='1.0' encoding='UTF-7'?>
<volume_types>
<volume_type id="1" name="SATA">
<extra_specs/>
</volume_type>
<volume_type id="2" name="SSD">
<extra_specs/>
</volume_type>
</volume_types>
HTTP response status codes

When an error occurs, Block Storage returns an HTTP error response code that denotes the
type of error. Some errors returns a response body, which returns additional information
about the error.
The following table describes the possible status codes:
5
July 29, 2014
Response status code Description
Response body?
200
Generic successful response.
Yes
201
Entity created.
Yes. Expect a location header and a response

body.
204
Successful response without body.
No
301
Redirection.
Yes
400
Invalid request (syntax, value, and so on).
Yes
401
Unauthenticated client.
Yes
403
Authenticated client unable to perform action. Yes
409
Action cannot be completed due to situation

that is possibly permanent.
Yes
415
Unsupported type.
Yes, with type details.
Limits
All accounts, by default, have a preconfigured set of thresholds (or limits) to manage
capacity and prevent abuse of the system. The system recognizes two kinds of limits: rate
limits and absolute limits. Rate limits are thresholds that are reset after a certain amount of
time passes. Absolute limits are fixed.
Absolute limits
The following table shows the absolute limits:
Table2.2.Absolute limits
Name
Description
Limit
Block Storage
Maximum amount of block storage
1 TB
Date and time format

Block Storage uses an ISO-8601 compliant date format for the display and consumption of
date time values.
Example2.3.DB service date and time format

yyyy-MM-dd'T'HH:mm:ss.SSSZ
May 19th, 2011 at 8:07:08 AM, GMT-5 has the following format:
2011-05-19T08:07:08-05:00
The following table describes the date time format codes:
Table2.3.Date time format codes

Code
Description
yyyy
Four digit year
MM
Two digit month
dd
Two digit day of month
July 29, 2014
Code
Description
Separator for date time
HH
Two digit hour of day (00-23)
mm
Two digit minutes of hour
ss
Two digit seconds of the minute
SSS
Three digit milliseconds of the second
RFC-822 timezone
Faults
When an error occurs, Block Storage returns a fault object containing an HTTP error
response code that denotes the type of error. The response body returns additional
information about the fault.
The following table lists possible fault types with their associated error codes and
descriptions.
Fault type
Associated
error code
Description
badRequest
400
The user request contains one or more errors.
unauthorized
401
The supplied token is not authorized to access the resources, either it's
expired or invalid.
forbidden
403
Access to the requested resource was denied.
itemNotFound
404
The back-end services did not find anything matching the Request-URI.
badMethod
405
The request method is not allowed for this resource.
overLimit
413
Either the number of entities in the request is larger than allowed limits,
or the user has exceeded allowable request rate limits. See the details
element for more specifics. Contact support if you think you need higher
request rate limits.
badMediaType
415
The requested content type is not supported by this service.
unprocessableEntity
422
The requested resource could not be processed on at the moment.
instanceFault
500
This is a generic server error and the message contains the reason for the
error. This error could wrap several error messages and is a catch all.
notImplemented
501
The requested method or resource is not implemented.
serviceUnavailable503
Block Storage is not available.
The following two instanceFault examples show errors when the server has erred or
cannot perform the requested operation:
Example2.4.Example instanceFault response: XML

HTTP/1.1 500 Internal Server Error
Content-Length: 121
Date: Mon, 28 Nov 2011 18:19:37 GMT
<?xml version="1.0" encoding="UTF-8"?>
<instanceFault code="500"
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content">
<message> The server has either erred or is incapable of
performing the requested operation. </message>
</instanceFault>
July 29, 2014
Example2.5.Example fault response: JSON

HTTP/1.1 500 Internal Server Error
Content-Length: 120
Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:33:48 GMT
{
"instanceFault":{
"code":500,
"message":"The server has either erred or is incapable of performing the
requested operation."
}
}
The error code (code) is returned in the body of the response for convenience. The
message element returns a human-readable message that is appropriate for display to the
end user. The details element is optional and may contain information that is useful for
tracking down an error, such as a stack trace. The details element may or may not be
appropriate for display to an end user, depending on the role and experience of the end
user.
The fault's root element (for example, instanceFault) may change depending on the
type of error.
The following two badRequest examples show errors when the volume size is invalid:
Example2.6.Example badRequest fault on volume size errors: XML

HTTP/1.1 400 None
Content-Length: 121
Date: Mon, 28 Nov 2011 18:19:37 GMT
<badRequest code="400"
<message> Volume 'size' needs to be a positive integer value, -1.0
cannot be accepted. </message>
</badRequest>
Example2.7.Example badRequest fault on volume size errors: JSON

HTTP/1.1 400 None
Content-Length: 120
Date: Tue, 29 Nov 2011 00:33:48 GMT
{
"badRequest":{
"code":400,
"message":"Volume 'size' needs to be a positive integer value, -1.0
cannot be accepted."
}
}
The next two examples show itemNotFound errors:

8
July 29, 2014
Example2.8.Example itemNotFound fault: XML

HTTP/1.1 404 Not Found
Content-Length: 147
Content-Type: application/xml; charset=UTF-8
Date: Mon, 28 Nov 2011 19:50:15 GMT
<itemNotFound code="404"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
<message> The resource could not be found. </message>
</itemNotFound>
Example2.9.Example itemNotFound fault: JSON

HTTP/1.1 404 Not Found
Content-Length: 78
Date: Tue, 29 Nov 2011 00:35:24 GMT
{
"itemNotFound":{
"code":404,
"message":"The resource could not be found."
}
}
July 29, 2014
3. API operations
Volumes ........................................................................................................................
Snapshots ......................................................................................................................
Volume types ................................................................................................................
Quality of service (QoS) specifications (qos-specs) ..........................................................
Quota sets extension (os-quota-sets) .............................................................................
Limits extension (limits) .................................................................................................
Backups extension .........................................................................................................
10
23
33
35
47
64
65
Volumes
A volume is a detachable block storage device. You can think of it as a USB hard drive. You
can attach a volume to one instance at a time.
When you create, list, or delete volumes, these status values are possible:
Status
Description
creating
The volume is being created.
available
The volume is ready to be attached to an instance.
attaching
The volume is attaching to an instance.
in-use
The volume is attached to an instance.
deleting
The volume is being deleted.
error
An error occurred during volume creation.
error_deleting
An error occurred during volume deletion.
backing-up
The volume is being backed up.
restoring-backup
A backup is being restored to the volume.
error_restoring
An error occurred during backup restoration to a volume.
Method
URI
Description
POST
/v2/{tenant_id}/volumes
Creates a volume.
GET
Lists summary information for all Block Storage volumes

that the tenant who submits the request can access.
GET
/v2/{tenant_id}/volumes/detail
Lists detailed information for all Block Storage volumes

GET
/v2/{tenant_id}/volumes/
{volume_id}
Shows information about a specified volume.
PUT
{volume_id}{?display_description,
display_name}
Updates a volume.
DELETE
{volume_id}
Deletes a specified volume.
10
July 29, 2014
Create volume
Method
POST
URI
Description
Creates a volume.
To create a bootable volume, include the image ID and set the bootable flag to true in
the request body.
Normal response codes: 202
Request
This table shows the URI parameters for the create volume request:
Name
{tenant_id}
Type
String
Description
The unique identifier of the tenant or account.
Example3.1.Create volume: JSON request

{
"volume": {
"availability_zone": null,
"source_volid": null,
"display_description": null,
"snapshot_id": null,
"size": 10,
"display_name": "my_volume",
"imageRef": null,
"volume_type": null,
"metadata": {}
}
}
This table shows the body parameters for the create volume request:
Name
availability_zone
Type
String
Description
The availability zone.
(Optional)
source_volid
Uuid
(Optional)
display_description
String
To create a volume from an existing volume, specify the ID of the

existing volume.
The volume description.
(Optional)
snapshot_id
Uuid
(Optional)
size
Int
To create a volume from an existing snapshot, specify the ID of the

existing volume snapshot.
The size of the volume, in GBs.
(Required)
display_name
String
The volume name.
(Optional)
imageRef
Uuid
The ID of the image from which you want to create the volume.
Required to create a bootable volume.
11
Name
July 29, 2014
Type
Description
(Optional)
volume_type
String
The associated volume type.
(Optional)
Boolean
bootable
(Optional)
String
metadata
(Optional)
Enables or disables the bootable attribute. You can boot an instance

from a bootable volume.
One or more metadata key and value pairs to associate with the
volume.
Example3.2.Create volume: XML request

<volume
xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
display_name="vol-001" display_description="Another volume."
size="2"/>
This operation does not accept a request body.
Response
Example3.3.Create volume: JSON response
{
"volume": {
"status": "creating",
"display_name": "my_volume",
"attachments": [],
"availability_zone": "nova",
"bootable": "false",
"created_at": "2014-02-21T19:52:04.949734",
"display_description": null,
"volume_type": "None",
"metadata": {},
"id": "93c2e2aa-7744-4fd6-a31a-80c4726b08d7",
"size": 10
}
}
This table shows the body parameters for the create volume response:
Name
status
Type
String
Description
The volume status.
(Required)
display_name
String
The volume name.
(Required)
attachments
String
One or more instance attachments.
(Required)
availability_zone
String
The availability zone.
(Required)
12
July 29, 2014
Name
bootable
Type
Boolean
(Required)
created_at
Datetime
Description
Enables or disables the bootable attribute. You can boot an instance
from a bootable volume.
Date and time when the volume was created.
(Required)
display_description
String
The volume description.
(Required)
volume_type
String
The associated volume type.
(Required)
snapshot_id
Uuid
(Required)
source_volid
Uuid
(Required)
metadata
String
(Required)
id
Uuid
To create a volume from an existing volume snapshot, specify the ID of

the existing volume snapshot.
To create a volume from an existing volume, specify the ID of the
existing volume.
One or more metadata key and value pairs to associate with the
volume.
The volume ID.
(Required)
size
Int
The size of the volume, in GBs.
(Required)
Example3.4.Create volume: XML response

<volume xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/volume/api/v1" status="creating"
display_name="vol-001" availability_zone="nova" bootable="false"
created_at="2014-02-21 20:18:33.122452"
display_description="Another volume." volume_type="None"
snapshot_id="None" source_volid="None"
id="83960a54-8dad-4fd8-bc41-33c71e098e04" size="2">
<attachments/>
<metadata/>
</volume>
This operation does not return a response body.
13
July 29, 2014
List volumes
Method
GET
URI
Description
Lists summary information for all Block Storage volumes
Request
This table shows the URI parameters for the list volumes request:
Name
{tenant_id}
Type
String
Description
Response
Example3.5.List volumes: XML response
<volumes xmlns:atom="http://www.w3.org/2005/Atom"
<volume name="vol-004" id="45baf976-c20a-4894-a7c3-c94b7376bf55">
<attachments/>
<metadata/>
</volume>
<volume name="vol-003" id="5aa119a8-d25b-45a7-8d1b-88e127885635">
<attachments/>
<metadata/>
</volume>
</volumes>
Example3.6.List volumes: JSON response

{
"volumes": [
{
"id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
"links": [
{
"href": "http://localhost:8776/v2/
0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3c94b7376bf55",
"rel": "self"
},
{
"href": "http://localhost:8776/
"rel": "bookmark"
}
],
"name": "vol-004"
14
July 29, 2014
},
{
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"links": [
{
v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8d25b-45a7-8d1b-88e127885635",
"rel": "self"
},
{
0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8d25b-45a7-8d1b-88e127885635",
"rel": "bookmark"
}
],
"name": "vol-003"
}
]
}
15
July 29, 2014
List volumes (detailed)

Method
GET
URI
Description
/v2/{tenant_id}/volumes/detail
Lists detailed information for all Block Storage volumes

Request
This table shows the URI parameters for the list volumes (detailed) request:
Name
{tenant_id}
Type
String
Description
Response
Example3.7.List volumes (detailed): XML response
<volumes
xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-blockstorage/2.0/content/Volume_Image_Metadata.html"
xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-blockstorage/2.0/content/Volume_Tenant_Attribute.html"
xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/
2.0/content/Volume_Host_Attribute.html"
xmlns:atom="http://www.w3.org/2005/Atom"
<volume status="available" name="vol-004" availability_zone="nova"
created_at="2013-02-25 06:36:28" description="Another volume."
volume_type="None" source_volid="None" snapshot_id="None"
id="45baf976-c20a-4894-a7c3-c94b7376bf55" size="1"
os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde"
os-vol-host-attr:host="ip-10-168-107-25">
<attachments/>
<metadata>
<meta key="contents">junk</meta>
</metadata>
</volume>
<volume status="available" name="vol-003" availability_zone="nova"
created_at="2013-02-25 02:40:21"
description="This is yet, another volume." volume_type="None"
source_volid="None" snapshot_id="None"
id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
<attachments/>
<metadata>
<meta key="contents">not junk</meta>
</metadata>
</volume>
16
July 29, 2014
</volumes>
Example3.8.List volumes (detailed): JSON response

{
"volumes": [
{
"status": "available",
"attachments": [],
"links": [
{
"rel": "self"
},
{
"rel": "bookmark"
}
],
"os-vol-host-attr:host": "ip-10-168-107-25",
"id": "45baf976-c20a-4894-a7c3-c94b7376bf55",
"description": "Another volume.",
"name": "vol-004",
"created_at": "2013-02-25T06:36:28.000000",
"os-vol-tenant-attr:tenant_id":
"0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"metadata": {
"contents": "junk"
}
},
{
"attachments": [],
"links": [
{
v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8d25b-45a7-8d1b-88e127885635",
"rel": "self"
},
{
"rel": "bookmark"
}
],
17
July 29, 2014
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"description": "This is yet, another volume.",
"name": "vol-003",
"created_at": "2013-02-25T02:40:21.000000",
"os-vol-tenant-attr:tenant_id":
"size": 1,
"metadata": {
"contents": "not junk"
}
}
]
}
18
July 29, 2014
Show volume information

Method
GET
URI
Description
Shows information about a specified volume.
{volume_id}
Request
This table shows the URI parameters for the show volume information request:
Name
Type
Description
{tenant_id}
String
{volume_id}
UUID
The unique identifier of an existing volume.
Response
Example3.9.Show volume information: XML response
<volume
xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-blockstorage/2.0/content/Volume_Image_Metadata.html"
xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-blockstorage/2.0/content/Volume_Tenant_Attribute.html"
xmlns:os-vol-host-attr="http://docs.openstack.org/openstack-block-storage/
2.0/content/Volume_Host_Attribute.html"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
status="available" name="vol-003" availability_zone="nova"
bootable="false" created_at="2013-02-25 02:40:21"
description="This is yet, another volume." volume_type="None"
id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
<attachments/>
<metadata>
</metadata>
</volume>
Example3.10.Show volume information: JSON response

{
"volume": {
"attachments": [],
"links": [
{
19
July 29, 2014
"rel": "self"
},
{
"rel": "bookmark"
}
],
"bootable": "false",
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"description": "Super volume.",
"name": "vol-002",
"created_at": "2013-02-25T02:40:21.000000",
"os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde",
"size": 1,
"metadata": {
}
}
}
20
July 29, 2014
Update volume
Method
PUT
URI
Description
{volume_id}{?display_description,
display_name}
Updates a volume.
Request
This table shows the URI parameters for the update volume request:
Name
Type
Description
{tenant_id}
String
{volume_id}
UUID
This table shows the query parameters for the update volume request:
Name
display_description
Type
String
Description
A description of the volume.
(Optional)
display_name
String
The name of the volume.
(Optional)
Example3.11.Update volume: XML request

<snapshot
display_name="vol-003" display_description="This is yet, another volume."/
>
Example3.12.Update volume: JSON request

{
"volume": {
"display_name": "vol-003",
"display_description": "This is yet, another volume."
}
}
Response
Example3.13.Update volume: XML response
<volume xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
status="available" display_name="vol-003" availability_zone="nova"
21
July 29, 2014
created_at="2013-02-25 02:40:21"
display_description="This is yet, another volume." volume_type="None"
id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1">
<attachments/>
<metadata>
</metadata>
</volume>
Example3.14.Update volume: JSON response

{
"volume": {
"attachments": [],
"links": [
{
"rel": "self"
},
{
"rel": "bookmark"
}
],
"id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"display_description": "This is yet, another volume.",
"created_at": "2013-02-25T02:40:21.000000",
"size": 1,
"metadata": {
}
}
}
22
July 29, 2014
Delete volume
Method
DELETE
URI
Description
Deletes a specified volume.
{volume_id}
Request
This table shows the URI parameters for the delete volume request:
Name
Type
Description
{tenant_id}
String
{volume_id}
UUID
Snapshots
A snapshot is a point in time copy of the data that a volume contains.
When you create, list, or delete snapshots, these status values are possible:
Status
Description
creating
The snapshot is being created.
available
The snapshot is ready to be used.
deleting
The snapshot is being deleted.
error
An error occurred during snapshot creation.
error_deleting
An error occurred during snapshot deletion.
Method
URI
Description
POST
/v2/{tenant_id}/snapshots
{?snapshot,volume_id,force,
display_name,display_description}
Creates a snapshot, which is a point-in-time copy of a

volume. You can create a volume from the snapshot.
GET
Lists summary information for all Block Storage snapshots

GET
/v2/{tenant_id}/snapshots/detail
Lists detailed information for all Block Storage snapshots

GET
/v2/{tenant_id}/snapshots/
{snapshot_id}
Shows information for a specified snapshot.
PUT
/v2/{tenant_id}/
snapshots/{snapshot_id}{?
display_description,display_name}
Updates a specified snapshot.
DELETE
{snapshot_id}
Deletes a specified snapshot.
23
July 29, 2014
Create snapshot
Method
POST
URI
Description
{?snapshot,volume_id,force,
display_name,display_description}
Creates a snapshot, which is a point-in-time copy of a

volume. You can create a volume from the snapshot.
Request
This table shows the URI parameters for the create snapshot request:
Name
{tenant_id}
Type
String
Description
This table shows the query parameters for the create snapshot request:
Name
snapshot
Type
String
Description
A partial representation of a snapshot used in the creation process.
(Required)
volume_id
String
(Required)
force
Boolean
(Optional)
display_name
String
To create a snapshot from an existing volume, specify the ID of the

existing volume.
[True/False] Indicate whether to snapshot, even if the volume is
attached. Default==False.
Name of the snapshot. Default==None.
(Optional)
display_description
String
Description of snapshot. Default==None.
(Optional)
Example3.15.Create snapshot: XML request

<snapshot
name="snap-001" description="Daily backup"
volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" force="true"/>
Example3.16.Create snapshot: JSON request

{
"snapshot": {
"name": "snap-001",
"description": "Daily backup",
"volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
"force": true
}
}

24
July 29, 2014
Response
Example3.17.Create snapshot: XML response
<snapshot status="creating" description="Daily backup"
created_at="2013-02-25T03:56:53.081642"
volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1"
id="ffa9bc5e-1172-4021-acaf-cdcd78a9584d" name="snap-001">
<metadata/>
</snapshot>
Example3.18.Create snapshot: JSON response

{
"snapshot": {
"status": "creating",
"created_at": "2013-02-25T03:56:53.081642",
"metadata": {},
"size": 1,
"id": "ffa9bc5e-1172-4021-acaf-cdcd78a9584d",
"name": "snap-001"
}
}
25
July 29, 2014
List snapshots
Method
GET
URI
Description
Lists summary information for all Block Storage snapshots
Request
This table shows the URI parameters for the list snapshots request:
Name
{tenant_id}
Type
String
Description
Response
Example3.19.List snapshots: XML response
<snapshots>
<snapshot status="available" description="Very important"
created_at="2013-02-25 04:13:17"
id="2bb856e1-b3d8-4432-a858-09e4ce939389" name="snap-001">
<metadata/>
</snapshot>
<snapshot status="available" description="Weekly backup"
created_at="2013-02-25 07:20:38"
volume_id="806092e3-7551-4fff-a005-49016f4943b1" size="1"
id="e820db06-58b5-439d-bac6-c01faa3f6499" name="snap-002">
<metadata/>
</snapshot>
</snapshots>
Example3.20.List snapshots: JSON response

{
"snapshots": [
{
"description": "Very important",
"created_at": "2013-02-25T04:13:17.000000",
"metadata": {},
"size": 1,
"id": "2bb856e1-b3d8-4432-a858-09e4ce939389",
"name": "snap-001"
},
{
"description": "Weekly backup",
"created_at": "2013-02-25T07:20:38.000000",
26
July 29, 2014
"metadata": {},
"volume_id": "806092e3-7551-4fff-a005-49016f4943b1",
"size": 1,
"id": "e820db06-58b5-439d-bac6-c01faa3f6499",
"name": "snap-002"
}
]
}
27
July 29, 2014
List snapshots (detailed)

Method
GET
URI
Description
/v2/{tenant_id}/snapshots/detail
Lists detailed information for all Block Storage snapshots

Request
This table shows the URI parameters for the list snapshots (detailed) request:
Name
{tenant_id}
Type
String
Description
Response
Example3.21.List snapshots (detailed): XML response
<snapshots
xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/
openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html">
<snapshot status="available" description="Daily backup"
created_at="2013-02-25 07:30:12"
id="43f20e0e-2c2c-4770-9d4e-c3d769ae5470" name="snap-001"
os-extended-snapshot-attributes:project_id=
"0c2eba2c5af04d3f9e9d0d410b371fde"
os-extended-snapshot-attributes:progress="100%">
<metadata/>
</snapshot>
<snapshot status="available" description="Weekly backup"
created_at="2013-02-25 07:20:38"
volume_id="806092e3-7551-4fff-a005-49016f4943b1" size="1"
id="e820db06-58b5-439d-bac6-c01faa3f6499" name="snap-002"
<metadata/>
</snapshot>
</snapshots>
Example3.22.List snapshots (detailed): JSON response

{
"snapshots": [
{
"os-extended-snapshot-attributes:progress": "100%",
"created_at": "2013-02-25T07:30:12.000000",
"metadata": {},
28
July 29, 2014
"os-extended-snapshot-attributes:project_id":
"size": 30,
"id": "43f20e0e-2c2c-4770-9d4e-c3d769ae5470",
"name": "snap-001"
},
{
"description": "Weekly backup",
"created_at": "2013-02-25T07:20:38.000000",
"metadata": {},
"volume_id": "806092e3-7551-4fff-a005-49016f4943b1",
"size": 1,
"id": "e820db06-58b5-439d-bac6-c01faa3f6499",
"name": "snap-002"
}
]
}
29
July 29, 2014
Show snapshot information

Method
GET
URI
Description
Shows information for a specified snapshot.
{snapshot_id}
Request
This table shows the URI parameters for the show snapshot information request:
Name
Type
Description
{tenant_id}
String
{snapshot_id}
UUID
The unique identifier of an existing snapshot.
Response
Example3.23.Show snapshot information: XML response
<snapshot
xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstackblock-storage/2.0/content/Extended_Snapshot_Attributes.html"
status="available" description="Very important"
created_at="2013-02-25 04:13:17"
id="2bb856e1-b3d8-4432-a858-09e4ce939389" name="snap-001"
<metadata/>
</snapshot>
Example3.24.Show snapshot information: JSON response

{
"snapshot": {
"created_at": "2013-02-25T04:13:17.000000",
"metadata": {},
"size": 1,
"id": "2bb856e1-b3d8-4432-a858-09e4ce939389",
"name": "snap-001"
}
}

30
July 29, 2014
Update snapshot
Method
PUT
URI
Description
/v2/{tenant_id}/
snapshots/{snapshot_id}{?
display_description,display_name}
Updates a specified snapshot.
Request
This table shows the URI parameters for the update snapshot request:
Name
Type
Description
{tenant_id}
String
{snapshot_id}
UUID
This table shows the query parameters for the update snapshot request:
Name
display_description
Type
String
Description
Describes the snapshot.
(Optional)
display_name
String
The name of the snapshot.
(Optional)
Example3.25.Update snapshot: XML request

<snapshot
display_name="snap-002" display_description="This is yet, another
snapshot."/>
Example3.26.Update snapshot: JSON request

{
"snapshot": {
"display_name": "snap-002",
"display_description": "This is yet, another snapshot."
}
}
Response
Example3.27.Update snapshot: XML response
<snapshot
xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstackblock-storage/2.0/content/Extended_Snapshot_Attributes.html"
31
July 29, 2014
status="available"
display_description="This is yet, another snapshot"
created_at="2013-02-20T08:11:34.000000"
volume_id="2402b902-0b7a-458c-9c07-7435a826f794"
size="1"
id="4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2"
display_name="vol-002"
<metadata/>
</snapshot>
Example3.28.Update snapshot: JSON response

{
"snapshot": {
"created_at": "2013-02-20T08:11:34.000000",
"display_description": "This is yet, another snapshot",
"id": "4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2",
"size": 1,
"volume_id": "2402b902-0b7a-458c-9c07-7435a826f794"
}
}
32
July 29, 2014
Delete snapshot
Method
DELETE
URI
Description
Deletes a specified snapshot.
{snapshot_id}
Request
This table shows the URI parameters for the delete snapshot request:
Name
Type
Description
{tenant_id}
String
{snapshot_id}
UUID
Volume types
Method
URI
Description
GET
/v2/{tenant_id}/types
Lists volume types.
GET
/v2/{tenant_id}/types/
{volume_type_id}
Shows information about a specified volume type.
33
July 29, 2014
List volume types

Method
GET
URI
Description
Lists volume types.
/v2/{tenant_id}/types
Request
This table shows the URI parameters for the list volume types request:
Name
{tenant_id}
Type
String
Description
Response
Example3.29.List volume types: XML response
<volume_types
<volume_type id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="SSD">
<extra_specs>
<extra_spec key="capabilities">gpu</extra_spec>
</extra_specs>
</volume_type>
<volume_type id="8eb69a46-df97-4e41-9586-9a40a7533803" name="SATA"
/>
</volume_types>
Example3.30.List volume types: JSON response

{
"volume_types": [
{
"extra_specs": {
"capabilities": "gpu"
},
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "SSD"
},
{
"extra_specs": {},
"id": "8eb69a46-df97-4e41-9586-9a40a7533803",
"name": "SATA"
}
]
}
34
July 29, 2014
Show volume type information

Method
GET
URI
Description
Shows information about a specified volume type.
/v2/{tenant_id}/types/
{volume_type_id}
Request
This table shows the URI parameters for the show volume type information request:
Name
Type
Description
{tenant_id}
String
{volume_type_id}
UUID
The unique identifier for an existing volume type.
Response
Example3.31.Show volume type information: JSON response
{
"volume_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "SSD",
"extra_specs": {
"capabilities": "gpu"
}
}
}
Example3.32.Show volume type information: XML response

<volume_type
id="6685584b-1eac-4da6-b5c3-555430cf68ff" name="SSD">
<extra_specs>
<extra_spec key="capabilities">gpu</extra_spec>
</extra_specs>
</volume_type>
Quality of service (QoS) specifications (qos-specs)

Administrators only, depending on policy settings. Create, list, show details for, associate,
disassociate, and delete quality of service (QoS) specifications.
Method
POST
URI
Description
Creates a QoS specification.
/v2/{tenant_id}/qos-specs
35
Method
July 29, 2014
URI
Description
GET
GET
/v2/{tenant_id}/qos-specs/{qos_id} Shows details for a specified QoS specification.
DELETE
/v2/{tenant_id}/qos-specs/{qos_id} Deletes a specified QoS specification.
GET
/v2/{tenant_id}/qos-specs/
{qos_id}/associate{?vol_type_id}
Associates a QoS specification with a specified volume

type.
GET
{qos_id}/disassociate{?
vol_type_id}
Disassociates a QoS specification from a specified volume

type.
GET
{qos_id}/disassociate_all
Disassociates a specified QoS specification from all

associations.
GET
{qos_id}/associations
Gets all associations for a specified QoS specification.
Lists quality of service (QoS) specifications.
36
July 29, 2014
Create QoS specification

Method
POST
URI
Description
Creates a QoS specification.
Request
This table shows the URI parameters for the create qos specification request:
Name
{tenant_id}
Type
String
Description
The unique ID of the tenant or account.
Example3.33.Create QoS specification: JSON request

{
"qos_specs": {
"availability": "100",
"name": "reliability-spec",
"numberOfFailures": "0"
}
}
This table shows the body parameters for the create qos specification request:
Name
qos_specs
Type
String
Description
A qos_specs object.
(Required)
name
String
The name of the QoS specification.
(Required)
specs
String
Specification key and value pairs.
(Required)
Example3.34.Create QoS specification: XML request

<qos_specs name="performance-spec" delay="0" throughput="100"/>
Response
Example3.35.Create QoS specification: JSON response
{
"qos_specs": {
"specs": {
},
37
July 29, 2014
"consumer": "back-end",
"id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
},
"links": [
{
"href": "http://23.253.228.211:8776/v2/
e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3b289-95205c50dd15",
"rel": "self"
},
{
"href": "http://23.253.228.211:8776/
"rel": "bookmark"
}
]
}
This table shows the body parameters for the create qos specification response:
Name
qos_specs
Type
String
Description
A qos_specs object.
(Required)
specs
String
A specs object.
(Required)
consumer
String
The consumer type.
(Required)
name
String
(Required)
id
Uuid
The generated ID for the QoS specification.
(Required)
links
Dict
The QoS specification links.
(Required)
Example3.36.Create QoS specification: XML response

<qos_specs>
<qos_spec consumer="back-end"
id="ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
name="performance-spec">
<specs>
<delay>0</delay>
<throughput>100</throughput>
</specs>
</qos_spec>
</qos_specs>
38
July 29, 2014
List QoS specs

Method
GET
URI
Description
Lists quality of service (QoS) specifications.
Normal response codes: 200, 300
Request
This table shows the URI parameters for the list qos specs request:
Name
{tenant_id}
Type
String
Description
Response
Example3.37.List QoS specs: JSON response
{
"qos_specs": [
{
"specs": {
},
"id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
},
{
"specs": {
"delay": "0",
"throughput": "100"
},
"name": "performance-spec",
"id": "ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
}
]
}
This table shows the body parameters for the list qos specs response:
Name
qos_specs
Type
String
Description
A qos_specs object.
(Required)
specs
String
(Required)
consumer
String
The consumer type.
(Required)
39
Name
name
July 29, 2014
Type
String
Description
(Required)
id
Uuid
(Required)
Example3.38.List QoS specs: XML response

<qos_specs>
id="0388d6c6-d5d4-42a3-b289-95205c50dd15"
name="reliability-spec">
<specs>
<availability>100</availability>
<numberOfFailures>0</numberOfFailures>
</specs>
</qos_spec>
id="ecfc6e2e-7117-44a4-8eec-f84d04f531a8"
name="performance-spec">
<specs>
<delay>0</delay>
<throughput>100</throughput>
</specs>
</qos_spec>
</qos_specs>
40
July 29, 2014
Show QoS specification details

Method
GET
URI
Description
/v2/{tenant_id}/qos-specs/{qos_id} Shows details for a specified QoS specification.

Error response codes: computeFault (400, 500, ), serviceUnavailable (503), badRequest
(400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413)
Request
This table shows the URI parameters for the show qos specification details request:
Name
Type
Description
{tenant_id}
String
{qos_id}
UUID
The UUID for the QoS specification.
Response
Example3.39.Show QoS specification details: JSON response
{
"qos_specs": {
"specs": {
},
"id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
},
"links": [
{
"href": "http://23.253.228.211:8776/v2/
"rel": "self"
},
{
"href": "http://23.253.228.211:8776/
"rel": "bookmark"
}
]
}
This table shows the body parameters for the show qos specification details response:
Name
qos_specs
Type
String
Description
A qos_specs object.
41
Name
July 29, 2014
Type
Description
(Required)
specs
String
(Required)
consumer
String
The consumer type.
(Required)
name
String
(Required)
id
Uuid
(Required)
links
Dict
The QoS specification links.
(Required)
Example3.40.Show QoS specification details: XML response

<qos_specs>
id="0388d6c6-d5d4-42a3-b289-95205c50dd15"
name="reliability-spec">
<specs>
<availability>100</availability>
<numberOfFailures>0</numberOfFailures>
</specs>
</qos_spec>
</qos_specs>
42
July 29, 2014
Delete QoS specification

Method
DELETE
URI
Description
/v2/{tenant_id}/qos-specs/{qos_id} Deletes a specified QoS specification.
Request
This table shows the URI parameters for the delete qos specification request:
Name
Type
Description
{tenant_id}
String
{qos_id}
UUID
{qos_id}
String
The unique ID of the QoS specification.
{force}
String
Optional flag that indicates whether to delete the specified QoS

specification even if it is in-use.
43
July 29, 2014
Associate QoS specification with volume type

Method
GET
URI
Description
{qos_id}/associate{?vol_type_id}
Associates a QoS specification with a specified volume

type.
Request
This table shows the URI parameters for the associate qos specification with volume type
request:
Name
Type
Description
{tenant_id}
String
{qos_id}
UUID
44
July 29, 2014
Disassociate QoS specification from volume type

Method
GET
URI
Description
Disassociates a QoS specification from a specified volume
type.
{qos_id}/disassociate{?
vol_type_id}
Request
This table shows the URI parameters for the disassociate qos specification from volume type
request:
Name
Type
Description
{tenant_id}
String
{qos_id}
UUID
45
July 29, 2014
Disassociate QoS specification from all associations

Method
GET
URI
Description
Disassociates a specified QoS specification from all
associations.
{qos_id}/disassociate_all
Request
This table shows the URI parameters for the disassociate qos specification from all
associations request:
Name
Type
Description
{tenant_id}
String
{qos_id}
UUID
46
July 29, 2014
Get all associations for QoS specification

Method
GET
URI
Description
Gets all associations for a specified QoS specification.
{qos_id}/associations
Request
This table shows the URI parameters for the get all associations for qos specification
request:
Name
Type
Description
{tenant_id}
String
{qos_id}
UUID
Response
Example3.41.Get all associations for QoS specification: XML response
<qos_associations>
<associations association_type="volume_type"
name="reliability-type"
id="a12983c2-83bd-4afa-be9f-ad796573ead6"/>
</qos_associations>
Example3.42.Get all associations for QoS specification: JSON response

{
"qos_associations": [
{
"association_type": "volume_type",
"name": "reliability-type",
"id": "a12983c2-83bd-4afa-be9f-ad796573ead6"
}
]
}
Quota sets extension (os-quota-sets)

Administrators only, depending on policy settings. View, update, and delete quotas for a
tenant.
Method
GET
URI
Description
/v2/{tenant_id}/os-quota-sets/
{tenant_id}
47
Shows quotas for a tenant.
Method
July 29, 2014
URI
Description
PUT
{tenant_id}
Updates quotas for a tenant.
DELETE
{tenant_id}
Deletes quotas for a tenant so the quotas revert to default

values.
GET
defaults
Gets default quotas for a tenant.
GET
{tenant_id}/{user_id}
Enables an admin user to show quotas for a specified

tenant and user.
POST
Updates quotas for a specified tenant/project and user.
DELETE
Deletes quotas for a user so that the quotas revert to

default values.
GET
{tenant_id}/detail/{user_id}
Shows details for quotas for a specified tenant and user.
48
July 29, 2014
Show quotas
Method
GET
URI
Description
{tenant_id}
Shows quotas for a tenant.
Request
This table shows the URI parameters for the show quotas request:
Name
Type
Description
{tenant_id}
String
The ID for the tenant or project in a multi-tenancy cloud.
{tenant_id}
String
The ID for the tenant for which you want to show, update, or delete
quotas. This ID is different from the first tenant ID that you specify in
the URI: That ID is for the admin tenant.
Response
Example3.43.Show quotas response: JSON
{
"quota_set": {
"cores": 20,
"fixed_ips": -1,
"floating_ips": 10,
"id": "fake_tenant",
"injected_file_content_bytes": 10240,
"injected_file_path_bytes": 255,
"injected_files": 5,
"instances": 10,
"key_pairs": 100,
"metadata_items": 128,
"ram": 51200,
"security_group_rules": 20,
"security_groups": 10
}
}
This table shows the body parameters for the show quotas response:
Name
quota_set
Type
String
Description
A quota_set object.
(Required)
cores
Int
The number of instance cores allowed for each tenant.
(Required)
fixed_ips
Int
(Required)
floating_ips
Int
The number of fixed IP addresses allowed for each tenant. Must be

equal to or greater than the number of allowed instances.
The number of floating IP addresses allowed for each tenant.
49
July 29, 2014
Name
Type
Description
(Required)
id
Int
The ID for the quota set.
(Required)
injected_file_content_bytesInt
The number of bytes of content allowed for each injected file.
(Required)
injected_file_path_bytes
Int
The number of bytes allowed for each injected file path.
(Required)
injected_files
Int
The number of injected files allowed for each tenant.
(Required)
instances
Int
The number of instances allowed for each tenant.
(Required)
key_pairs
Int
The number of key pairs allowed for each user.
(Required)
metadata_items
Int
The number of metadata items allowed for each instance.
(Required)
ram
Int
The amount of instance RAM in megabytes allowed for each tenant.
(Required)
security_group_rules
Int
The number of rules allowed for each security group.
(Optional)
security_groups
Int
The number of security groups allowed for each tenant.
(Required)
Example3.44.Show quotas response: XML

<quota_set id="fake_tenant">
<cores>20</cores>
<fixed_ips>-1</fixed_ips>
<floating_ips>10</floating_ips>
<injected_file_content_bytes>10240</injected_file_content_bytes>
<injected_file_path_bytes>255</injected_file_path_bytes>
<injected_files>5</injected_files>
<instances>10</instances>
<key_pairs>100</key_pairs>
<metadata_items>128</metadata_items>
<ram>51200</ram>
<security_group_rules>20</security_group_rules>
<security_groups>10</security_groups>
</quota_set>
50
July 29, 2014
Update quotas
Method
PUT
URI
Description
{tenant_id}
Updates quotas for a tenant.
Request
This table shows the URI parameters for the update quotas request:
Name
Type
Description
{tenant_id}
String
{tenant_id}
String
Example3.45.Update quotas response: JSON

{
"quota_set": {
}
}
This table shows the body parameters for the update quotas request:
Name
quota_set
Type
String
Description
A quota_set object.
(Required)
cores
Int
(Optional)
fixed_ips
Int
(Optional)
floating_ips
Int

(Optional)
id
Int
(Optional)
(Optional)
Int
(Optional)
injected_files
Int
(Optional)
instances
Int
(Optional)
51
July 29, 2014
Name
Type
Int
key_pairs
Description
(Optional)
metadata_items
Int
(Optional)
Int
ram
(Optional)
Int
(Optional)
security_groups
Int
(Optional)
Example3.46.Show quotas response: XML

</quota_set>
Response
Example3.47.Update quota response: JSON
{
"quota_set": {
"cores": 20,
"fixed_ips": -1,
"floating_ips": 10,
"instances": 10,
"key_pairs": 100,
"ram": 51200,
}
}
This table shows the body parameters for the update quotas response:
Name
quota_set
Type
String
Description
A quota_set object.
(Required)
cores
Int
(Required)
fixed_ips
Int
(Required)

52
July 29, 2014
Name
floating_ips
Type
Int
Description
(Required)
id
Int
(Required)
(Required)
Int
(Required)
injected_files
Int
(Required)
instances
Int
(Required)
key_pairs
Int
(Required)
metadata_items
Int
(Required)
ram
Int
(Required)
Int
(Optional)
security_groups
Int
(Required)
Example3.48.Update quota response: XML

<quota_set>
<cores>20</cores>
<ram>51200</ram>
</quota_set>
53
July 29, 2014
Delete quotas
Method
DELETE
URI
Description
{tenant_id}
Deletes quotas for a tenant so the quotas revert to default

values.
Request
This table shows the URI parameters for the delete quotas request:
Name
Type
Description
{tenant_id}
String
{tenant_id}
String
54
July 29, 2014
Get default quotas

Method
GET
URI
Description
defaults
Gets default quotas for a tenant.
Request
This table shows the URI parameters for the get default quotas request:
Name
{tenant_id}
Type
String
Description
Response
Example3.49.Get default quotas response: JSON
{
"quota_set": {
"cores": 20,
"fixed_ips": -1,
"floating_ips": 10,
"instances": 10,
"key_pairs": 100,
"ram": 51200,
}
}
This table shows the body parameters for the get default quotas response:
Name
quota_set
Type
String
Description
A quota_set object.
(Required)
cores
Int
(Required)
fixed_ips
Int
(Required)
floating_ips
Int

(Required)
id
Int
55
July 29, 2014
Name
Type
Description
(Required)
(Required)
Int
(Required)
injected_files
Int
(Required)
instances
Int
(Required)
key_pairs
Int
(Required)
metadata_items
Int
(Required)
ram
Int
(Required)
Int
(Optional)
security_groups
Int
(Required)
Example3.50.Get default quotas response: XML

<cores>20</cores>
<ram>51200</ram>
</quota_set>
56
July 29, 2014
Show quotas for user

Method
GET
URI
Description
Enables an admin user to show quotas for a specified

tenant and user.
Request
This table shows the URI parameters for the show quotas for user request:
Name
Type
Description
{tenant_id}
String
{tenant_id}
String
The ID for the tenant for which you want to show or update quotas.
This ID is different from the first tenant ID that you specify in the URI:
That ID is for the admin tenant.
{user_id}
String
The user ID. Specify in the URI as a query string:

user_id={user_id}.
Response
Example3.51.Show quotas for user response: JSON
{
"quota_set": {
"cores": 20,
"fixed_ips": -1,
"floating_ips": 10,
"instances": 10,
"key_pairs": 100,
"ram": 51200,
}
}
This table shows the body parameters for the show quotas for user response:
Name
quota_set
Type
String
Description
A quota_set object.
(Required)
cores
Int
(Required)
fixed_ips
Int

57
July 29, 2014
Name
Type
Description
(Required)
floating_ips
Int
(Required)
id
Int
(Required)
(Required)
Int
(Required)
injected_files
Int
(Required)
instances
Int
(Required)
key_pairs
Int
(Required)
metadata_items
Int
(Required)
ram
Int
(Required)
Int
(Optional)
security_groups
Int
(Required)
Example3.52.Show quotas for user response: XML

<cores>20</cores>
<ram>51200</ram>
</quota_set>
58
July 29, 2014
Update quotas for user

Method
POST
URI
Description
Updates quotas for a specified tenant/project and user.
Request
This table shows the URI parameters for the update quotas for user request:
Name
Type
Description
{tenant_id}
String
{tenant_id}
String
{user_id}
String

user_id={user_id}.
Example3.53.Update quotas for user request: JSON

{
"quota_set": {
"force": "True",
"instances": 9
}
}
This table shows the body parameters for the update quotas for user request:
Name
quota_set
Type
String
Description
A quota_set object.
(Required)
cores
Int
(Optional)
fixed_ips
Int
(Optional)
floating_ips
Int

(Optional)
id
Int
(Optional)
(Optional)
Int
(Optional)
injected_files
Int
(Optional)
59
July 29, 2014
Name
Type
Int
instances
Description
(Optional)
Int
key_pairs
(Optional)
metadata_items
Int
(Optional)
Int
ram
(Optional)
Int
(Optional)
security_groups
Int
(Optional)
Example3.54.Update quotas for user request: XML

<force>True</force>
</quota_set>
Response
Example3.55.Update quotas for user response: JSON
{
"quota_set": {
"cores": 20,
"floating_ips": 10,
"fixed_ips": -1,
"instances": 9,
"key_pairs": 100,
"ram": 51200,
}
}
This table shows the body parameters for the update quotas for user response:
Name
quota_set
Type
String
Description
A quota_set object.
(Required)
cores
Int
60
July 29, 2014
Name
Type
Description
(Required)
fixed_ips
Int
(Required)
floating_ips
Int

(Required)
id
Int
(Required)
(Required)
Int
(Required)
injected_files
Int
(Required)
instances
Int
(Required)
key_pairs
Int
(Required)
metadata_items
Int
(Required)
ram
Int
(Required)
Int
(Optional)
security_groups
Int
(Required)
Example3.56.Show quotas for user response: XML

<quota_set>
<cores>20</cores>
<ram>51200</ram>
</quota_set>
61
July 29, 2014
Delete quotas for user

Method
DELETE
URI
Description
Deletes quotas for a user so that the quotas revert to

default values.
Request
This table shows the URI parameters for the delete quotas for user request:
Name
Type
Description
{tenant_id}
String
{tenant_id}
String
{user_id}
String

user_id={user_id}.
62
July 29, 2014
Show quota details for user

Method
GET
URI
Description
{tenant_id}/detail/{user_id}
Shows details for quotas for a specified tenant and user.
Request
This table shows the URI parameters for the show quota details for user request:
Name
Type
Description
{tenant_id}
String
{tenant_id}
String
{user_id}
String

user_id={user_id}.
Response
Example3.57.Show quota details for user response: JSON
{
"quota_set": {
"cores": {
"in_use": 0,
"limit": 20,
"reserved": 0
},
"fixed_ips": {
"in_use": 0,
"limit": -1,
"reserved": 0
},
"floating_ips": {
"in_use": 0,
"limit": 10,
"reserved": 0
},
"injected_files": {
"in_use": 0,
"limit": 5,
"reserved": 0
},
"instances": {
"in_use": 0,
"limit": 10,
"reserved": 0
},
"key_pairs": {
"in_use": 0,
63
July 29, 2014
"limit": 100,
"reserved": 0
},
"metadata_items": {
"in_use": 0,
"limit": 128,
"reserved": 0
},
"ram": {
"in_use": 0,
"limit": 51200,
"reserved": 0
},
"security_groups": {
"in_use": 0,
"limit": 10,
"reserved": 0
},
"injected_file_content_bytes": {
"in_use": 0,
"limit": 10240,
"reserved": 0
},
"injected_file_path_bytes": {
"in_use": 0,
"limit": 255,
"reserved": 0
},
"security_group_rules": {
"in_use": 0,
"limit": 20,
"reserved": 0
}
}
}
Limits extension (limits)

Show absolute limits for a tenant.
Method
GET
URI
Description
Shows absolute limits for a tenant.
/v2/{tenant_id}/limits
64
July 29, 2014
Show absolute limits

Method
GET
URI
Description
Shows absolute limits for a tenant.
/v2/{tenant_id}/limits
Normal response codes: 200, 203
Request
This table shows the URI parameters for the show absolute limits request:
Name
{tenant_id}
Type
String
Description
Response
Example3.58.Show absolute limits: JSON response
{
"limits": {
"rate": [],
"absolute": {
"totalSnapshotsUsed": 0,
"maxTotalVolumeGigabytes": 1000,
"totalGigabytesUsed": 0,
"maxTotalSnapshots": 10,
"totalVolumesUsed": 0,
"maxTotalVolumes": 10
}
}
}
Example3.59.Show absolute limits: XML response

<limits xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/common/api/v1.0">
<rates/>
<absolute>
<limit name="totalSnapshotsUsed" value="0"/>
<limit name="maxTotalVolumeGigabytes" value="1000"/>
<limit name="totalGigabytesUsed" value="0"/>
<limit name="maxTotalSnapshots" value="10"/>
<limit name="totalVolumesUsed" value="0"/>
<limit name="maxTotalVolumes" value="10"/>
</absolute>
</limits>
Backups extension
A backup is a full copy of a volume stored in an external service. The service can be
configured. The only supported service for now is Object Storage. A backup can
65
July 29, 2014
subsequently be restored from the external service to either the same volume that the
backup was originally taken from, or to a new volume. backup and restore operations can
only be carried out on volumes which are in an unattached and available state.
When you create, list, or delete backups, these status values are possible:
Status
Description
creating
The backup is being created.
available
The backup is ready to be restored to a volume.
deleting
The backup is being deleted.
error
An error has occurred with the backup.
restoring
The backup is being restored to a volume.
error_restoring
An error occurred during backup restoration to a volume.
In the event of an error, more information about the error can be found in the
fail_reason field for the backup.
Method
URI
Description
POST
/v2/{tenant_id}/backups
Creates a Block Storage backup from a volume.
GET
Lists backups defined in Block Storage to which the tenant

who submits the request has access.
GET
/v2/{tenant_id}/backups/detail
Lists detailed information for backups defined in Block

Storage to which the tenant who submits the request has
access.
GET
/v2/{tenant_id}/backups/
{backup_id}
Shows details for a specified backup.
DELETE
{backup_id}
Deletes a specified backup.
POST
{backup_id}/restore
Restores a Block Storage backup to an existing or new

Block Storage volume.
66
July 29, 2014
Create backup
Method
POST
URI
Description
Creates a Block Storage backup from a volume.
Request
This table shows the URI parameters for the create backup request:
Name
{tenant_id}
Type
String
Description
Example3.60.Create backup: JSON request

{
"backup": {
"container": null,
"description": null,
"name": "backup001",
"volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607"
}
}
Response
Example3.61.Create backup: JSON response
{
"backup": {
"id": "deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
"links": [
{
c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71acaa-889c2d5d5c8e",
"rel": "self"
},
{
c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71acaa-889c2d5d5c8e",
"rel": "bookmark"
}
],
"name": "backup001"
}
}
67
July 29, 2014
List backups
Method
GET
URI
Description
Lists backups defined in Block Storage to which the tenant
who submits the request has access.
Request
This table shows the URI parameters for the list backups request:
Name
{tenant_id}
Type
String
Description
Response
Example3.62.List backups: JSON response
{
"backups": [
{
"id": "2ef47aee-8844-490c-804d-2a8efe561c65",
"links": [
{
v1/c95fc3e4afe248a49a28828f286a7b38/backups/
2ef47aee-8844-490c-804d-2a8efe561c65",
"rel": "self"
},
{
c95fc3e4afe248a49a28828f286a7b38/backups/
2ef47aee-8844-490c-804d-2a8efe561c65",
"rel": "bookmark"
}
],
"name": "backup001"
},
{
"id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
"links": [
{
4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
"rel": "self"
},
{
4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
"rel": "bookmark"
68
July 29, 2014
}
],
"name": "backup002"
}
]
}
69
July 29, 2014
List backups (detailed)

Method
GET
URI
Description
/v2/{tenant_id}/backups/detail
Lists detailed information for backups defined in Block

Storage to which the tenant who submits the request has
access.
Request
This table shows the URI parameters for the list backups (detailed) request:
Name
{tenant_id}
Type
String
Description
Response
Example3.63.List backups (detailed): JSON response
{
"backups": [
{
"availability_zone": "az1",
"container": "volumebackups",
"created_at": "2013-04-02T10:35:27.000000",
"fail_reason": null,
"id": "2ef47aee-8844-490c-804d-2a8efe561c65",
"links": [
{
2ef47aee-8844-490c-804d-2a8efe561c65",
"rel": "self"
},
{
2ef47aee-8844-490c-804d-2a8efe561c65",
"rel": "bookmark"
}
],
"object_count": 22,
"size": 1,
"volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6"
},
{
"created_at": "2013-04-02T10:21:48.000000",
70
July 29, 2014
"id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
"links": [
{
4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
"rel": "self"
},
{
4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8",
"rel": "bookmark"
}
],
"object_count": 22,
"size": 1,
}
]
}
71
July 29, 2014
Show backup details

Method
GET
URI
Description
Shows details for a specified backup.
{backup_id}
Request
This table shows the URI parameters for the show backup details request:
Name
Type
Description
{tenant_id}
String
{backup_id}
UUID
The unique identifier for a backup.
Response
Example3.64.Show backup details: JSON response
{
"backup": {
"created_at": "2013-04-02T10:35:27.000000",
"id": "2ef47aee-8844-490c-804d-2a8efe561c65",
"links": [
{
2ef47aee-8844-490c-804d-2a8efe561c65",
"rel": "self"
},
{
2ef47aee-8844-490c-804d-2a8efe561c65",
"rel": "bookmark"
}
],
"object_count": 22,
"size": 1,
}
}
72
July 29, 2014
Delete backup
Method
DELETE
URI
Description
Deletes a specified backup.
{backup_id}
Request
This table shows the URI parameters for the delete backup request:
Name
Type
Description
{tenant_id}
String
{backup_id}
UUID
73
July 29, 2014
Restore backup
Method
POST
URI
Description
Restores a Block Storage backup to an existing or new
Block Storage volume.
{backup_id}/restore
Request
This table shows the URI parameters for the restore backup request:
Name
Type
Description
{tenant_id}
String
{backup_id}
UUID
Example3.65.Restore backup: JSON request

{
"restore": {
"volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607"
}
}
Response
Example3.66.Restore backup: JSON response
{
"restore": {
"backup_id": "2ef47aee-8844-490c-804d-2a8efe561c65",
"volume_id": "795114e8-7489-40be-a978-83797f2c1dd3"
}
}
74

Openstack Blockstorage API Ref

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Openstack Blockstorage API Ref

Uploaded by

Copyright:

Available Formats

docs.openstack.

Block Storage API Reference

July 29, 2014

API v2 and extensions

OpenStack Block Storage API v2 Reference

Copyright 2013, 2014 OpenStack Foundation All rights reserved.

Block Storage API Reference

July 29, 2014

API v2 and extensions

Block Storage API Reference

July 29, 2014

API v2 and extensions

Block Storage API Reference

July 29, 2014

API v2 and extensions

Block Storage API Reference

July 29, 2014

API v2 and extensions

3.40. Show QoS specification details: XML response .......................................................

Block Storage API Reference

July 29, 2014

API v2 and extensions

Block Storage API Reference

July 29, 2014

API v2 and extensions

Block Storage API Reference

July 29, 2014

API v2 and extensions

Block Storage API Reference

July 29, 2014

API v2 and extensions

High-level task flow

You create a volume.

The command returns the 521752a6-acf6-4b2d-bc7a-119f9148cd8c volume

You attach that volume to a virtual machine (VM) with the

Block Storage API Reference

July 29, 2014

API v2 and extensions

2. General API information

Block Storage API Reference

July 29, 2014

API v2 and extensions

Request and response types

In the request example below, notice that Content-Type is set to application/json,

Example2.1.Request with headers: Get volume types

An XML response format is returned:

Example2.2.Response with headers

HTTP response status codes

Block Storage API Reference

July 29, 2014

API v2 and extensions

Response status code Description

Generic successful response.

Yes. Expect a location header and a response

Successful response without body.

Invalid request (syntax, value, and so on).

Authenticated client unable to perform action. Yes

Action cannot be completed due to situation

Yes, with type details.

Maximum amount of block storage

Date and time format

Example2.3.DB service date and time format

The following table describes the date time format codes:

Table2.3.Date time format codes