Openstack Blockstorage API Ref

docs.openstack.org

http://docs.openstack.org

Block Storage API Reference July 29, 2014 API v2 and extensions

ii

OpenStack Block Storage API v2 ReferenceAPI 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 StorageApplication 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. Youmay 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 governingpermissions and limitations under the License.

http://www.apache.org/licenses/LICENSE-2.0


iii

Table of ContentsPreface ............................................................................................................................ 7

Intended audience .................................................................................................. 7Additional resources ................................................................................................ 7

1. Overview ..................................................................................................................... 1Glossary .................................................................................................................. 2High-level task flow ................................................................................................. 3

2. General API information ............................................................................................. 4Authentication ........................................................................................................ 4Request and response types .................................................................................... 5HTTP response status codes .................................................................................... 5Limits ...................................................................................................................... 6Date and time format ............................................................................................. 6Faults ...................................................................................................................... 7

3. API operations .......................................................................................................... 10Volumes ................................................................................................................ 10Snapshots .............................................................................................................. 23Volume types ........................................................................................................ 33Quality of service (QoS) specifications (qos-specs) .................................................. 35Quota sets extension (os-quota-sets) ..................................................................... 47Limits extension (limits) ......................................................................................... 64Backups extension ................................................................................................. 65


iv

List of Tables2.1. Response formats ..................................................................................................... 52.2. Absolute limits ......................................................................................................... 62.3. Date time format codes ........................................................................................... 6


v

List of Examples2.1. Request with headers: Get volume types .................................................................. 52.2. Response with headers ............................................................................................. 52.3. DB service date and time format .............................................................................. 62.4. Example instanceFault response: XML ....................................................................... 72.5. Example fault response: JSON .................................................................................. 82.6. Example badRequest fault on volume size errors: XML .............................................. 82.7. Example badRequest fault on volume size errors: JSON ............................................. 82.8. Example itemNotFound fault: XML ........................................................................... 92.9. Example itemNotFound fault: JSON .......................................................................... 93.1. Create volume: JSON request ................................................................................. 113.2. Create volume: XML request .................................................................................. 123.3. Create volume: JSON response ............................................................................... 123.4. Create volume: XML response ................................................................................ 133.5. List volumes: XML response .................................................................................... 143.6. List volumes: JSON response ................................................................................... 143.7. List volumes (detailed): XML response .................................................................... 163.8. List volumes (detailed): JSON response ................................................................... 173.9. Show volume information: XML response ............................................................... 193.10. Show volume information: JSON response ............................................................ 193.11. Update volume: XML request ............................................................................... 213.12. Update volume: JSON request .............................................................................. 213.13. Update volume: XML response ............................................................................. 213.14. Update volume: JSON response ............................................................................ 223.15. Create snapshot: XML request .............................................................................. 243.16. Create snapshot: JSON request ............................................................................. 243.17. Create snapshot: XML response ............................................................................ 253.18. Create snapshot: JSON response ........................................................................... 253.19. List snapshots: XML response ................................................................................ 263.20. List snapshots: JSON response ............................................................................... 263.21. List snapshots (detailed): XML response ................................................................ 283.22. List snapshots (detailed): JSON response ............................................................... 283.23. Show snapshot information: XML response ........................................................... 303.24. Show snapshot information: JSON response .......................................................... 303.25. Update snapshot: XML request ............................................................................. 313.26. Update snapshot: JSON request ............................................................................ 313.27. Update snapshot: XML response ........................................................................... 313.28. Update snapshot: JSON response .......................................................................... 323.29. List volume types: XML response .......................................................................... 343.30. List volume types: JSON response ......................................................................... 343.31. Show volume type information: JSON response ..................................................... 353.32. Show volume type information: XML response ...................................................... 353.33. Create QoS specification: JSON request ................................................................. 373.34. Create QoS specification: XML request .................................................................. 373.35. Create QoS specification: JSON response ............................................................... 373.36. Create QoS specification: XML response ................................................................ 383.37. List QoS specs: JSON response .............................................................................. 393.38. List QoS specs: XML response ............................................................................... 403.39. Show QoS specification details: JSON response ...................................................... 41


vi

3.40. Show QoS specification details: XML response ....................................................... 423.41. Get all associations for QoS specification: XML response ........................................ 473.42. Get all associations for QoS specification: JSON response ....................................... 473.43. Show quotas response: JSON ................................................................................ 493.44. Show quotas response: XML ................................................................................. 503.45. Update quotas response: JSON ............................................................................. 513.46. Show quotas response: XML ................................................................................. 523.47. Update quota response: JSON .............................................................................. 523.48. Update quota response: XML ............................................................................... 533.49. Get default quotas response: JSON ....................................................................... 553.50. Get default quotas response: XML ........................................................................ 563.51. Show quotas for user response: JSON ................................................................... 573.52. Show quotas for user response: XML .................................................................... 583.53. Update quotas for user request: JSON .................................................................. 593.54. Update quotas for user request: XML ................................................................... 603.55. Update quotas for user response: JSON ................................................................ 603.56. Show quotas for user response: XML .................................................................... 613.57. Show quota details for user response: JSON .......................................................... 633.58. Show absolute limits: JSON response .................................................................... 653.59. Show absolute limits: XML response ..................................................................... 653.60. Create backup: JSON request ................................................................................ 673.61. Create backup: JSON response .............................................................................. 673.62. List backups: JSON response ................................................................................. 683.63. List backups (detailed): JSON response .................................................................. 703.64. Show backup details: JSON response .................................................................... 723.65. Restore backup: JSON request .............................................................................. 743.66. Restore backup: JSON response ............................................................................ 74


7

PrefaceIntended audience .......................................................................................................... 7Additional resources ........................................................................................................ 7

OpenStack Block Storage provides volume management with the OpenStack Computeservice.

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 audienceThis guide assists software developers who develop applications by using the Block StorageAPI 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 resourcesYou 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.

http://bugs.launchpad.net/cinder

http://docs.openstack.org/api/

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html


1

1. OverviewGlossary .......................................................................................................................... 2High-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 morecompute resources.

• Use high performance storage to serve database or I/O-intensive applications.

You interact with Block Storage programmatically through the Block Storage API asdescribed in this guide.

Note

• OpenStack Block Storage is an add-on feature to OpenStack Nova Computein Folsom versions and earlier.

• Block Storage is multi-tenant rather than dedicated.

• Block Storage allows you to create snapshots that you can save, list, andrestore.

• Block Storage allows you to create backups of your volumes to ObjectStorage for archival and disaster recovery purposes. These backups can besubsequently restored to the same volume or new volumes.


2

GlossaryTo 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 beattached to one instance at a time.

• Volume type

A type of a block storage volume. You can define whatever types work best for you, suchas 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. Theonly supported service for now is Object Storage. A backup can subsequently be restoredfrom the external service to either the same volume that the backup was originally takenfrom, or to a new volume.


3

High-level task flowProcedure 1.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 volumeID.

2. You attach that volume to a virtual machine (VM) with the616fb98f-46ca-475e-917e-2563e5a8cd19 ID, as follows:

For example:

$ nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb


4

2. General API informationAuthentication ................................................................................................................ 4Request and response types ............................................................................................ 5HTTP response status codes ............................................................................................ 5Limits .............................................................................................................................. 6Date and time format ..................................................................................................... 6Faults .............................................................................................................................. 7

The Block Storage API is implemented using a ReSTful web service interface. Like otherOpenStack projects, Block Storage shares a common token-based authentication systemthat allows access between products and services.

Note

All requests to authenticate against and operate the service are performedusing SSL over HTTP (HTTPS) on TCP port 443.

AuthenticationYou can use cURL to try the authentication process in two steps: get a token, and send thetoken to a service.

1. Get an authentication token by providing your user name and either your API key oryour 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 youridentity has already been authenticated. To use the token, pass it to other services as anX-Auth-Token header.

Authentication also returns a service catalog, listing the endpoints you can use for Cloudservices.

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 tore-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.

Important

If you programmatically parse an authentication response, be aware thatservice names are stable for the life of the particular service and can be used askeys. You should also be aware that a user's service catalog can include multipleuniquely-named services that perform similar functions.

http://curl.haxx.se/


5

Request and response typesThe Block Storage API supports both the JSON and XML data serialization formats. Therequest format is specified using the Content-Type header and is required for calls thathave a request body. The response format can be specified in requests either by using theAccept header or by adding an .xml or .json extension to the request URI. Note thatit is possible for a response to be serialized using a format different from the request. If noresponse format is specified, JSON is the default. If conflicting formats are specified usingboth an Accept header and a query extension, the query extension takes precedence.

Table 2.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:

Example 2.1. Request with headers: Get volume types

GET /v2/441446/types HTTP/1.1Host: dfw.blockstorage.api.openstackcloud.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbbAccept: application/xml

An XML response format is returned:

Example 2.2. Response with headers

HTTP/1.1 200 OKDate: Fri, 20 Jul 2012 20:32:13 GMTContent-Length: 187Content-Type: application/xmlX-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 codesWhen an error occurs, Block Storage returns an HTTP error response code that denotes thetype of error. Some errors returns a response body, which returns additional informationabout the error.

The following table describes the possible status codes:


6

Response status code Description Response body?

200 Generic successful response. Yes

201 Entity created. Yes. Expect a location header and a responsebody.

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 situationthat is possibly permanent.

Yes

415 Unsupported type. Yes, with type details.

LimitsAll accounts, by default, have a preconfigured set of thresholds (or limits) to managecapacity and prevent abuse of the system. The system recognizes two kinds of limits: ratelimits and absolute limits. Rate limits are thresholds that are reset after a certain amount oftime passes. Absolute limits are fixed.

Absolute limits

The following table shows the absolute limits:

Table 2.2. Absolute limits

Name Description Limit

Block Storage Maximum amount of block storage 1 TB

Date and time formatBlock Storage uses an ISO-8601 compliant date format for the display and consumption ofdate time values.

Example 2.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:

Table 2.3. Date time format codes

Code Description

yyyy Four digit year

MM Two digit month

dd Two digit day of month


7

Code Description

T 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

Z RFC-822 timezone

FaultsWhen an error occurs, Block Storage returns a fault object containing an HTTP errorresponse code that denotes the type of error. The response body returns additionalinformation about the fault.

The following table lists possible fault types with their associated error codes anddescriptions.

Fault type Associatederror 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'sexpired 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 detailselement for more specifics. Contact support if you think you need higherrequest rate limits.

badMediaType 415 The requested content type is not supported by this service.

unprocessableEntity422 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 theerror. 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 orcannot perform the requested operation:

Example 2.4. Example instanceFault response: XML

HTTP/1.1 500 Internal Server ErrorContent-Type: application/xmlContent-Length: 121Date: 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>


8

Example 2.5. Example fault response: JSON

HTTP/1.1 500 Internal Server ErrorContent-Length: 120Content-Type: application/json; charset=UTF-8Date: 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. Themessage element returns a human-readable message that is appropriate for display to theend user. The details element is optional and may contain information that is useful fortracking down an error, such as a stack trace. The details element may or may not beappropriate for display to an end user, depending on the role and experience of the enduser.

The fault's root element (for example, instanceFault) may change depending on thetype of error.

The following two badRequest examples show errors when the volume size is invalid:

Example 2.6. Example badRequest fault on volume size errors: XML

HTTP/1.1 400 NoneContent-Type: application/xmlContent-Length: 121Date: Mon, 28 Nov 2011 18:19:37 GMT

<?xml version="1.0" encoding="UTF-8"?><badRequest code="400" xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"> <message> Volume 'size' needs to be a positive integer value, -1.0 cannot be accepted. </message></badRequest>

Example 2.7. Example badRequest fault on volume size errors: JSON

HTTP/1.1 400 NoneContent-Length: 120Content-Type: application/json; charset=UTF-8Date: 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:


9

Example 2.8. Example itemNotFound fault: XML

HTTP/1.1 404 Not FoundContent-Length: 147Content-Type: application/xml; charset=UTF-8Date: Mon, 28 Nov 2011 19:50:15 GMT

<?xml version="1.0" encoding="UTF-8"?><itemNotFound code="404" xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"> <message> The resource could not be found. </message></itemNotFound>

Example 2.9. Example itemNotFound fault: JSON

HTTP/1.1 404 Not FoundContent-Length: 78Content-Type: application/json; charset=UTF-8Date: Tue, 29 Nov 2011 00:35:24 GMT

{ "itemNotFound":{ "code":404, "message":"The resource could not be found." }}


10

3. API operationsVolumes ........................................................................................................................ 10Snapshots ...................................................................................................................... 23Volume types ................................................................................................................ 33Quality of service (QoS) specifications (qos-specs) .......................................................... 35Quota sets extension (os-quota-sets) ............................................................................. 47Limits extension (limits) ................................................................................................. 64Backups extension ......................................................................................................... 65

VolumesA volume is a detachable block storage device. You can think of it as a USB hard drive. Youcan 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 /v2/{tenant_id}/volumes Lists summary information for all Block Storage volumesthat the tenant who submits the request can access.

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

GET /v2/{tenant_id}/volumes/{volume_id}

Shows information about a specified volume.

PUT /v2/{tenant_id}/volumes/{volume_id}{?display_description,display_name}

Updates a volume.

DELETE /v2/{tenant_id}/volumes/{volume_id}

Deletes a specified volume.


11

Create volume


POST /v2/{tenant_id}/volumes Creates a volume.

To create a bootable volume, include the image ID and set the bootable flag to true inthe request body.

Normal response codes: 202

Request

This table shows the URI parameters for the create volume request:

Name Type Description

{tenant_id} String The unique identifier of the tenant or account.

Example 3.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:


availability_zone String

(Optional)

The availability zone.

source_volid Uuid

(Optional)

To create a volume from an existing volume, specify the ID of theexisting volume.

display_description String

(Optional)

The volume description.

snapshot_id Uuid

(Optional)

To create a volume from an existing snapshot, specify the ID of theexisting volume snapshot.

size Int

(Required)

The size of the volume, in GBs.

display_name String

(Optional)

The volume name.

imageRef Uuid The ID of the image from which you want to create the volume.Required to create a bootable volume.


12


(Optional)

volume_type String

(Optional)

The associated volume type.

bootable Boolean

(Optional)

Enables or disables the bootable attribute. You can boot an instancefrom a bootable volume.

metadata String

(Optional)

One or more metadata key and value pairs to associate with thevolume.

Example 3.2. Create volume: XML request

<?xml version="1.0" encoding="UTF-8"?><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

Example 3.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", "snapshot_id": null, "source_volid": null, "metadata": {}, "id": "93c2e2aa-7744-4fd6-a31a-80c4726b08d7", "size": 10 }}

This table shows the body parameters for the create volume response:


status String

(Required)

The volume status.

display_name String

(Required)

The volume name.

attachments String

(Required)

One or more instance attachments.

availability_zone String

(Required)

The availability zone.


13


bootable Boolean

(Required)

Enables or disables the bootable attribute. You can boot an instancefrom a bootable volume.

created_at Datetime

(Required)

Date and time when the volume was created.


(Required)

The volume description.

volume_type String

(Required)

The associated volume type.

snapshot_id Uuid

(Required)

To create a volume from an existing volume snapshot, specify the ID ofthe existing volume snapshot.

source_volid Uuid

(Required)

To create a volume from an existing volume, specify the ID of theexisting volume.

metadata String

(Required)

One or more metadata key and value pairs to associate with thevolume.

id Uuid

(Required)

The volume ID.

size Int

(Required)

The size of the volume, in GBs.

Example 3.4. Create volume: XML response

<?xml version='1.0' encoding='UTF-8'?><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.


14

List volumes


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


Request

This table shows the URI parameters for the list volumes request:




Response

Example 3.5. List volumes: XML response

<?xml version='1.0' encoding='UTF-8'?><volumes xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"> <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>

Example 3.6. List volumes: JSON response

{ "volumes": [ { "id": "45baf976-c20a-4894-a7c3-c94b7376bf55", "links": [ { "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55", "rel": "self" }, { "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55", "rel": "bookmark" } ], "name": "vol-004"


15

}, { "id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "links": [ { "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "self" }, { "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "bookmark" } ], "name": "vol-003" } ]}



16

List volumes (detailed)


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


Request

This table shows the URI parameters for the list volumes (detailed) request:




Response

Example 3.7. List volumes (detailed): XML response

<?xml version='1.0' encoding='UTF-8'?><volumes xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html" xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/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"> <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" os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde" os-vol-host-attr:host="ip-10-168-107-25"> <attachments/> <metadata> <meta key="contents">not junk</meta> </metadata> </volume>


17

</volumes>

Example 3.8. List volumes (detailed): JSON response

{ "volumes": [ { "status": "available", "attachments": [], "links": [ { "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55", "rel": "self" }, { "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/45baf976-c20a-4894-a7c3-c94b7376bf55", "rel": "bookmark" } ], "availability_zone": "nova", "os-vol-host-attr:host": "ip-10-168-107-25", "source_volid": null, "snapshot_id": null, "id": "45baf976-c20a-4894-a7c3-c94b7376bf55", "description": "Another volume.", "name": "vol-004", "created_at": "2013-02-25T06:36:28.000000", "volume_type": "None", "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde", "size": 1, "metadata": { "contents": "junk" } }, { "status": "available", "attachments": [], "links": [ { "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "self" }, { "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "bookmark" } ], "availability_zone": "nova", "os-vol-host-attr:host": "ip-10-168-107-25", "source_volid": null, "snapshot_id": null,


18

"id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "description": "This is yet, another volume.", "name": "vol-003", "created_at": "2013-02-25T02:40:21.000000", "volume_type": "None", "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde", "size": 1, "metadata": { "contents": "not junk" } } ]}



19

Show volume information


GET /v2/{tenant_id}/volumes/{volume_id}

Shows information about a specified volume.


Request

This table shows the URI parameters for the show volume information request:



{volume_id} UUID The unique identifier of an existing volume.


Response

Example 3.9. Show volume information: XML response

<?xml version='1.0' encoding='UTF-8'?><volume xmlns:os-vol-image-meta="http://docs.openstack.org/openstack-block-storage/2.0/content/Volume_Image_Metadata.html" xmlns:os-vol-tenant-attr="http://docs.openstack.org/openstack-block-storage/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" source_volid="None" snapshot_id="None" id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1" os-vol-tenant-attr:tenant_id="0c2eba2c5af04d3f9e9d0d410b371fde" os-vol-host-attr:host="ip-10-168-107-25"> <attachments/> <metadata> <meta key="contents">not junk</meta> </metadata></volume>

Example 3.10. Show volume information: JSON response

{ "volume": { "status": "available", "attachments": [], "links": [ {


20

"href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "self" }, { "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "bookmark" } ], "availability_zone": "nova", "bootable": "false", "os-vol-host-attr:host": "ip-10-168-107-25", "source_volid": null, "snapshot_id": null, "id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "description": "Super volume.", "name": "vol-002", "created_at": "2013-02-25T02:40:21.000000", "volume_type": "None", "os-vol-tenant-attr:tenant_id": "0c2eba2c5af04d3f9e9d0d410b371fde", "size": 1, "metadata": { "contents": "not junk" } }}



21

Update volume


PUT /v2/{tenant_id}/volumes/{volume_id}{?display_description,display_name}

Updates a volume.


Request

This table shows the URI parameters for the update volume request:




This table shows the query parameters for the update volume request:



(Optional)

A description of the volume.

display_name String

(Optional)

The name of the volume.

Example 3.11. Update volume: XML request

<?xml version="1.0" encoding="UTF-8"?><snapshot xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" display_name="vol-003" display_description="This is yet, another volume."/>

Example 3.12. Update volume: JSON request

{ "volume": { "display_name": "vol-003", "display_description": "This is yet, another volume." }}


Response

Example 3.13. Update volume: XML response

<?xml version='1.0' encoding='UTF-8'?><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"


22

created_at="2013-02-25 02:40:21" display_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>

Example 3.14. Update volume: JSON response

{ "volume": { "status": "available", "attachments": [], "links": [ { "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "self" }, { "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635", "rel": "bookmark" } ], "availability_zone": "nova", "source_volid": null, "snapshot_id": null, "id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "display_description": "This is yet, another volume.", "display_name": "vol-003", "created_at": "2013-02-25T02:40:21.000000", "volume_type": "None", "size": 1, "metadata": { "contents": "not junk" } }}



23

Delete volume


DELETE /v2/{tenant_id}/volumes/{volume_id}

Deletes a specified volume.


Request

This table shows the URI parameters for the delete volume request:





SnapshotsA 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.


POST /v2/{tenant_id}/snapshots{?snapshot,volume_id,force,display_name,display_description}

Creates a snapshot, which is a point-in-time copy of avolume. You can create a volume from the snapshot.

GET /v2/{tenant_id}/snapshots Lists summary information for all Block Storage snapshotsthat the tenant who submits the request can access.

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

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 /v2/{tenant_id}/snapshots/{snapshot_id}

Deletes a specified snapshot.


24

Create snapshot


POST /v2/{tenant_id}/snapshots{?snapshot,volume_id,force,display_name,display_description}

Creates a snapshot, which is a point-in-time copy of avolume. You can create a volume from the snapshot.


Request

This table shows the URI parameters for the create snapshot request:



This table shows the query parameters for the create snapshot request:


snapshot String

(Required)

A partial representation of a snapshot used in the creation process.

volume_id String

(Required)

To create a snapshot from an existing volume, specify the ID of theexisting volume.

force Boolean

(Optional)

[True/False] Indicate whether to snapshot, even if the volume isattached. Default==False.

display_name String

(Optional)

Name of the snapshot. Default==None.


(Optional)

Description of snapshot. Default==None.

Example 3.15. Create snapshot: XML request

<?xml version="1.0" encoding="UTF-8"?><snapshot xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" name="snap-001" description="Daily backup" volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" force="true"/>

Example 3.16. Create snapshot: JSON request

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



25

Response

Example 3.17. Create snapshot: XML response

<?xml version='1.0' encoding='UTF-8'?><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>

Example 3.18. Create snapshot: JSON response

{ "snapshot": { "status": "creating", "description": "Daily backup", "created_at": "2013-02-25T03:56:53.081642", "metadata": {}, "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "size": 1, "id": "ffa9bc5e-1172-4021-acaf-cdcd78a9584d", "name": "snap-001" }}



26

List snapshots


GET /v2/{tenant_id}/snapshots Lists summary information for all Block Storage snapshotsthat the tenant who submits the request can access.


Request

This table shows the URI parameters for the list snapshots request:




Response

Example 3.19. List snapshots: XML response

<?xml version='1.0' encoding='UTF-8'?><snapshots> <snapshot status="available" description="Very important" created_at="2013-02-25 04:13:17" volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1" 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>

Example 3.20. List snapshots: JSON response

{ "snapshots": [ { "status": "available", "description": "Very important", "created_at": "2013-02-25T04:13:17.000000", "metadata": {}, "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "size": 1, "id": "2bb856e1-b3d8-4432-a858-09e4ce939389", "name": "snap-001" }, { "status": "available", "description": "Weekly backup", "created_at": "2013-02-25T07:20:38.000000",


27

"metadata": {}, "volume_id": "806092e3-7551-4fff-a005-49016f4943b1", "size": 1, "id": "e820db06-58b5-439d-bac6-c01faa3f6499", "name": "snap-002" } ]}



28

List snapshots (detailed)


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


Request

This table shows the URI parameters for the list snapshots (detailed) request:




Response

Example 3.21. List snapshots (detailed): XML response

<?xml version='1.0' encoding='UTF-8'?><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" volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="30" 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" os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde" os-extended-snapshot-attributes:progress="100%"> <metadata/> </snapshot></snapshots>

Example 3.22. List snapshots (detailed): JSON response

{ "snapshots": [ { "status": "available", "os-extended-snapshot-attributes:progress": "100%", "description": "Daily backup", "created_at": "2013-02-25T07:30:12.000000", "metadata": {},


29

"volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde", "size": 30, "id": "43f20e0e-2c2c-4770-9d4e-c3d769ae5470", "name": "snap-001" }, { "status": "available", "os-extended-snapshot-attributes:progress": "100%", "description": "Weekly backup", "created_at": "2013-02-25T07:20:38.000000", "metadata": {}, "volume_id": "806092e3-7551-4fff-a005-49016f4943b1", "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde", "size": 1, "id": "e820db06-58b5-439d-bac6-c01faa3f6499", "name": "snap-002" } ]}



30

Show snapshot information


GET /v2/{tenant_id}/snapshots/{snapshot_id}

Shows information for a specified snapshot.


Request

This table shows the URI parameters for the show snapshot information request:



{snapshot_id} UUID The unique identifier of an existing snapshot.


Response

Example 3.23. Show snapshot information: XML response

<?xml version='1.0' encoding='UTF-8'?><snapshot xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html" status="available" description="Very important" created_at="2013-02-25 04:13:17" volume_id="5aa119a8-d25b-45a7-8d1b-88e127885635" size="1" id="2bb856e1-b3d8-4432-a858-09e4ce939389" name="snap-001" os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde" os-extended-snapshot-attributes:progress="100%"> <metadata/></snapshot>

Example 3.24. Show snapshot information: JSON response

{ "snapshot": { "status": "available", "os-extended-snapshot-attributes:progress": "100%", "description": "Daily backup", "created_at": "2013-02-25T04:13:17.000000", "metadata": {}, "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635", "os-extended-snapshot-attributes:project_id": "0c2eba2c5af04d3f9e9d0d410b371fde", "size": 1, "id": "2bb856e1-b3d8-4432-a858-09e4ce939389", "name": "snap-001" }}



31

Update snapshot


PUT /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:




This table shows the query parameters for the update snapshot request:



(Optional)

Describes the snapshot.

display_name String

(Optional)

The name of the snapshot.

Example 3.25. Update snapshot: XML request

<?xml version="1.0" encoding="UTF-8"?><snapshot xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" display_name="snap-002" display_description="This is yet, another snapshot."/>

Example 3.26. Update snapshot: JSON request

{ "snapshot": { "display_name": "snap-002", "display_description": "This is yet, another snapshot." }}


Response

Example 3.27. Update snapshot: XML response

<?xml version='1.0' encoding='UTF-8'?><snapshot xmlns:os-extended-snapshot-attributes="http://docs.openstack.org/openstack-block-storage/2.0/content/Extended_Snapshot_Attributes.html"


32

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" os-extended-snapshot-attributes:project_id="0c2eba2c5af04d3f9e9d0d410b371fde" os-extended-snapshot-attributes:progress="100%"> <metadata/></snapshot>

Example 3.28. Update snapshot: JSON response

{ "snapshot": { "created_at": "2013-02-20T08:11:34.000000", "display_description": "This is yet, another snapshot", "display_name": "vol-002", "id": "4b502fcb-1f26-45f8-9fe5-3b9a0a52eaf2", "size": 1, "status": "available", "volume_id": "2402b902-0b7a-458c-9c07-7435a826f794" }}



33

Delete snapshot


DELETE /v2/{tenant_id}/snapshots/{snapshot_id}

Deletes a specified snapshot.


Request

This table shows the URI parameters for the delete snapshot request:





Volume typesMethod 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.


34

List volume types


GET /v2/{tenant_id}/types Lists volume types.


Request

This table shows the URI parameters for the list volume types request:




Response

Example 3.29. List volume types: XML response

<?xml version="1.0" encoding="UTF-8"?><volume_types xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"> <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>

Example 3.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" } ]}



35

Show volume type information


GET /v2/{tenant_id}/types/{volume_type_id}

Shows information about a specified volume type.


Request

This table shows the URI parameters for the show volume type information request:



{volume_type_id} UUID The unique identifier for an existing volume type.


Response

Example 3.31. Show volume type information: JSON response

{ "volume_type": { "id": "6685584b-1eac-4da6-b5c3-555430cf68ff", "name": "SSD", "extra_specs": { "capabilities": "gpu" } }}

Example 3.32. Show volume type information: XML response

<?xml version="1.0" encoding="UTF-8"?><volume_type xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content" 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.


POST /v2/{tenant_id}/qos-specs Creates a QoS specification.


36


GET /v2/{tenant_id}/qos-specs Lists quality of service (QoS) specifications.

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 volumetype.

GET /v2/{tenant_id}/qos-specs/{qos_id}/disassociate{?vol_type_id}

Disassociates a QoS specification from a specified volumetype.

GET /v2/{tenant_id}/qos-specs/{qos_id}/disassociate_all

Disassociates a specified QoS specification from allassociations.

GET /v2/{tenant_id}/qos-specs/{qos_id}/associations

Gets all associations for a specified QoS specification.


37

Create QoS specification


POST /v2/{tenant_id}/qos-specs Creates a QoS specification.


Request

This table shows the URI parameters for the create qos specification request:


{tenant_id} String The unique ID of the tenant or account.

Example 3.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:


qos_specs String

(Required)

A qos_specs object.

name String

(Required)

The name of the QoS specification.

specs String

(Required)

Specification key and value pairs.

Example 3.34. Create QoS specification: XML request

<?xml version="1.0" encoding="UTF-8"?><qos_specs name="performance-spec" delay="0" throughput="100"/>


Response

Example 3.35. Create QoS specification: JSON response

{ "qos_specs": { "specs": { "availability": "100", "numberOfFailures": "0" },


38

"consumer": "back-end", "name": "reliability-spec", "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15" }, "links": [ { "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15", "rel": "self" }, { "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15", "rel": "bookmark" } ]}

This table shows the body parameters for the create qos specification response:


qos_specs String

(Required)

A qos_specs object.

specs String

(Required)

A specs object.

consumer String

(Required)

The consumer type.

name String

(Required)


id Uuid

(Required)

The generated ID for the QoS specification.

links Dict

(Required)

The QoS specification links.

Example 3.36. Create QoS specification: XML response

<?xml version='1.0' encoding='UTF-8'?><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>



39

List QoS specs


GET /v2/{tenant_id}/qos-specs Lists quality of service (QoS) specifications.

Normal response codes: 200, 300

Request

This table shows the URI parameters for the list qos specs request:




Response

Example 3.37. List QoS specs: JSON response

{ "qos_specs": [ { "specs": { "availability": "100", "numberOfFailures": "0" }, "consumer": "back-end", "name": "reliability-spec", "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15" }, { "specs": { "delay": "0", "throughput": "100" }, "consumer": "back-end", "name": "performance-spec", "id": "ecfc6e2e-7117-44a4-8eec-f84d04f531a8" } ]}

This table shows the body parameters for the list qos specs response:


qos_specs String

(Required)

A qos_specs object.

specs String

(Required)


consumer String

(Required)

The consumer type.


40


name String

(Required)


id Uuid

(Required)


Example 3.38. List QoS specs: XML response

<?xml version='1.0' encoding='UTF-8'?><qos_specs> <qos_spec consumer="back-end" id="0388d6c6-d5d4-42a3-b289-95205c50dd15" name="reliability-spec"> <specs> <availability>100</availability> <numberOfFailures>0</numberOfFailures> </specs> </qos_spec> <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>



41

Show QoS specification details


GET /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:



{qos_id} UUID The UUID for the QoS specification.


Response

Example 3.39. Show QoS specification details: JSON response

{ "qos_specs": { "specs": { "availability": "100", "numberOfFailures": "0" }, "consumer": "back-end", "name": "reliability-spec", "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15" }, "links": [ { "href": "http://23.253.228.211:8776/v2/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15", "rel": "self" }, { "href": "http://23.253.228.211:8776/e1cf63117ae74309a5bcc2002a23be8b/qos_specs/0388d6c6-d5d4-42a3-b289-95205c50dd15", "rel": "bookmark" } ]}

This table shows the body parameters for the show qos specification details response:


qos_specs String A qos_specs object.


42


(Required)

specs String

(Required)


consumer String

(Required)

The consumer type.

name String

(Required)


id Uuid

(Required)


links Dict

(Required)

The QoS specification links.

Example 3.40. Show QoS specification details: XML response

<?xml version='1.0' encoding='UTF-8'?><qos_specs> <qos_spec consumer="back-end" id="0388d6c6-d5d4-42a3-b289-95205c50dd15" name="reliability-spec"> <specs> <availability>100</availability> <numberOfFailures>0</numberOfFailures> </specs> </qos_spec></qos_specs>



43

Delete QoS specification


DELETE /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:




{qos_id} String The unique ID of the QoS specification.

{force} String Optional flag that indicates whether to delete the specified QoSspecification even if it is in-use.



44

Associate QoS specification with volume type


GET /v2/{tenant_id}/qos-specs/{qos_id}/associate{?vol_type_id}

Associates a QoS specification with a specified volumetype.


Request

This table shows the URI parameters for the associate qos specification with volume typerequest:






45

Disassociate QoS specification from volume type


GET /v2/{tenant_id}/qos-specs/{qos_id}/disassociate{?vol_type_id}

Disassociates a QoS specification from a specified volumetype.


Request

This table shows the URI parameters for the disassociate qos specification from volume typerequest:






46

Disassociate QoS specification from all associations


GET /v2/{tenant_id}/qos-specs/{qos_id}/disassociate_all

Disassociates a specified QoS specification from allassociations.


Request

This table shows the URI parameters for the disassociate qos specification from allassociations request:






47

Get all associations for QoS specification


GET /v2/{tenant_id}/qos-specs/{qos_id}/associations

Gets all associations for a specified QoS specification.


Request

This table shows the URI parameters for the get all associations for qos specificationrequest:





Response

Example 3.41. Get all associations for QoS specification: XML response

<?xml version='1.0' encoding='UTF-8'?><qos_associations> <associations association_type="volume_type" name="reliability-type" id="a12983c2-83bd-4afa-be9f-ad796573ead6"/></qos_associations>

Example 3.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 atenant.


GET /v2/{tenant_id}/os-quota-sets/{tenant_id}

Shows quotas for a tenant.


48


PUT /v2/{tenant_id}/os-quota-sets/{tenant_id}

Updates quotas for a tenant.

DELETE /v2/{tenant_id}/os-quota-sets/{tenant_id}

Deletes quotas for a tenant so the quotas revert to defaultvalues.

GET /v2/{tenant_id}/os-quota-sets/defaults

Gets default quotas for a tenant.

GET /v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Enables an admin user to show quotas for a specifiedtenant and user.

POST /v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Updates quotas for a specified tenant/project and user.

DELETE /v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Deletes quotas for a user so that the quotas revert todefault values.

GET /v2/{tenant_id}/os-quota-sets/{tenant_id}/detail/{user_id}

Shows details for quotas for a specified tenant and user.


49

Show quotas


GET /v2/{tenant_id}/os-quota-sets/{tenant_id}

Shows quotas for a tenant.


Request

This table shows the URI parameters for the show quotas request:


{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 deletequotas. This ID is different from the first tenant ID that you specify inthe URI: That ID is for the admin tenant.


Response

Example 3.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:


quota_set String

(Required)

A quota_set object.

cores Int

(Required)

The number of instance cores allowed for each tenant.

fixed_ips Int

(Required)

The number of fixed IP addresses allowed for each tenant. Must beequal to or greater than the number of allowed instances.

floating_ips Int The number of floating IP addresses allowed for each tenant.


50


(Required)

id Int

(Required)

The ID for the quota set.

injected_file_content_bytesInt

(Required)

The number of bytes of content allowed for each injected file.

injected_file_path_bytes Int

(Required)

The number of bytes allowed for each injected file path.

injected_files Int

(Required)

The number of injected files allowed for each tenant.

instances Int

(Required)

The number of instances allowed for each tenant.

key_pairs Int

(Required)

The number of key pairs allowed for each user.

metadata_items Int

(Required)

The number of metadata items allowed for each instance.

ram Int

(Required)

The amount of instance RAM in megabytes allowed for each tenant.

security_group_rules Int

(Optional)

The number of rules allowed for each security group.

security_groups Int

(Required)

The number of security groups allowed for each tenant.

Example 3.44. Show quotas response: XML

<?xml version='1.0' encoding='UTF-8'?><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>



51

Update quotas


PUT /v2/{tenant_id}/os-quota-sets/{tenant_id}

Updates quotas for a tenant.


Request

This table shows the URI parameters for the update quotas request:




Example 3.45. Update quotas response: JSON

{ "quota_set": { "security_groups": 45 }}

This table shows the body parameters for the update quotas request:


quota_set String

(Required)

A quota_set object.

cores Int

(Optional)


fixed_ips Int

(Optional)


floating_ips Int

(Optional)

The number of floating IP addresses allowed for each tenant.

id Int

(Optional)



(Optional)



(Optional)


injected_files Int

(Optional)


instances Int

(Optional)



52


key_pairs Int

(Optional)


metadata_items Int

(Optional)


ram Int

(Optional)



(Optional)


security_groups Int

(Optional)


Example 3.46. Show quotas response: XML

<?xml version='1.0' encoding='UTF-8'?><quota_set id="fake_tenant"> <security_groups>45</security_groups></quota_set>


Response

Example 3.47. Update quota response: JSON

{ "quota_set": { "cores": 20, "fixed_ips": -1, "floating_ips": 10, "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": 45 }}

This table shows the body parameters for the update quotas response:


quota_set String

(Required)

A quota_set object.

cores Int

(Required)


fixed_ips Int

(Required)



53


floating_ips Int

(Required)


id Int

(Required)



(Required)



(Required)


injected_files Int

(Required)


instances Int

(Required)


key_pairs Int

(Required)


metadata_items Int

(Required)


ram Int

(Required)



(Optional)


security_groups Int

(Required)


Example 3.48. Update quota response: XML

<?xml version='1.0' encoding='UTF-8'?><quota_set> <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>45</security_groups></quota_set>



54

Delete quotas


DELETE /v2/{tenant_id}/os-quota-sets/{tenant_id}

Deletes quotas for a tenant so the quotas revert to defaultvalues.


Request

This table shows the URI parameters for the delete quotas request:






55

Get default quotas


GET /v2/{tenant_id}/os-quota-sets/defaults

Gets default quotas for a tenant.


Request

This table shows the URI parameters for the get default quotas request:




Response

Example 3.49. Get default quotas response: JSON


This table shows the body parameters for the get default quotas response:


quota_set String

(Required)

A quota_set object.

cores Int

(Required)


fixed_ips Int

(Required)


floating_ips Int

(Required)


id Int The ID for the quota set.


56


(Required)


(Required)



(Required)


injected_files Int

(Required)


instances Int

(Required)


key_pairs Int

(Required)


metadata_items Int

(Required)


ram Int

(Required)



(Optional)


security_groups Int

(Required)


Example 3.50. Get default quotas response: XML




57

Show quotas for user


GET /v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Enables an admin user to show quotas for a specifiedtenant and user.


Request

This table shows the URI parameters for the show quotas for user request:



{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

Example 3.51. Show quotas for user response: JSON


This table shows the body parameters for the show quotas for user response:


quota_set String

(Required)

A quota_set object.

cores Int

(Required)


fixed_ips Int The number of fixed IP addresses allowed for each tenant. Must beequal to or greater than the number of allowed instances.


58


(Required)

floating_ips Int

(Required)


id Int

(Required)



(Required)



(Required)


injected_files Int

(Required)


instances Int

(Required)


key_pairs Int

(Required)


metadata_items Int

(Required)


ram Int

(Required)



(Optional)


security_groups Int

(Required)


Example 3.52. Show quotas for user response: XML




59

Update quotas for user


POST /v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Updates quotas for a specified tenant/project and user.


Request

This table shows the URI parameters for the update quotas for user request:





Example 3.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:


quota_set String

(Required)

A quota_set object.

cores Int

(Optional)


fixed_ips Int

(Optional)


floating_ips Int

(Optional)


id Int

(Optional)



(Optional)



(Optional)


injected_files Int

(Optional)



60


instances Int

(Optional)


key_pairs Int

(Optional)


metadata_items Int

(Optional)


ram Int

(Optional)



(Optional)


security_groups Int

(Optional)


Example 3.54. Update quotas for user request: XML

<?xml version='1.0' encoding='UTF-8'?><quota_set id="fake_tenant"> <force>True</force> <instances>9</instances></quota_set>


Response

Example 3.55. Update quotas for user response: JSON

{ "quota_set": { "cores": 20, "floating_ips": 10, "fixed_ips": -1, "injected_file_content_bytes": 10240, "injected_file_path_bytes": 255, "injected_files": 5, "instances": 9, "key_pairs": 100, "metadata_items": 128, "ram": 51200, "security_group_rules": 20, "security_groups": 10 }}

This table shows the body parameters for the update quotas for user response:


quota_set String

(Required)

A quota_set object.

cores Int The number of instance cores allowed for each tenant.


61


(Required)

fixed_ips Int

(Required)


floating_ips Int

(Required)


id Int

(Required)



(Required)



(Required)


injected_files Int

(Required)


instances Int

(Required)


key_pairs Int

(Required)


metadata_items Int

(Required)


ram Int

(Required)



(Optional)


security_groups Int

(Required)


Example 3.56. Show quotas for user response: XML

<?xml version='1.0' encoding='UTF-8'?><quota_set> <cores>20</cores> <floating_ips>10</floating_ips> <fixed_ips>-1</fixed_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>9</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>



62

Delete quotas for user


DELETE /v2/{tenant_id}/os-quota-sets/{tenant_id}/{user_id}

Deletes quotas for a user so that the quotas revert todefault values.


Request

This table shows the URI parameters for the delete quotas for user request:







63

Show quota details for user


GET /v2/{tenant_id}/os-quota-sets/{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:






Response

Example 3.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,


64

"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.


GET /v2/{tenant_id}/limits Shows absolute limits for a tenant.


65

Show absolute limits


GET /v2/{tenant_id}/limits Shows absolute limits for a tenant.

Normal response codes: 200, 203

Request

This table shows the URI parameters for the show absolute limits request:




Response

Example 3.58. Show absolute limits: JSON response

{ "limits": { "rate": [], "absolute": { "totalSnapshotsUsed": 0, "maxTotalVolumeGigabytes": 1000, "totalGigabytesUsed": 0, "maxTotalSnapshots": 10, "totalVolumesUsed": 0, "maxTotalVolumes": 10 } }}

Example 3.59. Show absolute limits: XML response

<?xml version='1.0' encoding='UTF-8'?><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 extensionA backup is a full copy of a volume stored in an external service. The service can beconfigured. The only supported service for now is Object Storage. A backup can


66

subsequently be restored from the external service to either the same volume that thebackup was originally taken from, or to a new volume. backup and restore operations canonly 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 thefail_reason field for the backup.


POST /v2/{tenant_id}/backups Creates a Block Storage backup from a volume.

GET /v2/{tenant_id}/backups Lists backups defined in Block Storage to which the tenantwho submits the request has access.

GET /v2/{tenant_id}/backups/detail Lists detailed information for backups defined in BlockStorage to which the tenant who submits the request hasaccess.

GET /v2/{tenant_id}/backups/{backup_id}

Shows details for a specified backup.

DELETE /v2/{tenant_id}/backups/{backup_id}

Deletes a specified backup.

POST /v2/{tenant_id}/backups/{backup_id}/restore

Restores a Block Storage backup to an existing or newBlock Storage volume.


67

Create backup


POST /v2/{tenant_id}/backups Creates a Block Storage backup from a volume.


Request

This table shows the URI parameters for the create backup request:



Example 3.60. Create backup: JSON request

{ "backup": { "container": null, "description": null, "name": "backup001", "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607" }}

Response

Example 3.61. Create backup: JSON response

{ "backup": { "id": "deac8b8c-35c9-4c71-acaa-889c2d5d5c8e", "links": [ { "href": "http://localhost:8776/v2/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e", "rel": "self" }, { "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e", "rel": "bookmark" } ], "name": "backup001" }}


68

List backups


GET /v2/{tenant_id}/backups Lists backups defined in Block Storage to which the tenantwho submits the request has access.


Request

This table shows the URI parameters for the list backups request:




Response

Example 3.62. List backups: JSON response

{ "backups": [ { "id": "2ef47aee-8844-490c-804d-2a8efe561c65", "links": [ { "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65", "rel": "self" }, { "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65", "rel": "bookmark" } ], "name": "backup001" }, { "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8", "links": [ { "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8", "rel": "self" }, { "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8", "rel": "bookmark"


69

} ], "name": "backup002" } ]}


70

List backups (detailed)


GET /v2/{tenant_id}/backups/detail Lists detailed information for backups defined in BlockStorage to which the tenant who submits the request hasaccess.


Request

This table shows the URI parameters for the list backups (detailed) request:




Response

Example 3.63. List backups (detailed): JSON response

{ "backups": [ { "availability_zone": "az1", "container": "volumebackups", "created_at": "2013-04-02T10:35:27.000000", "description": null, "fail_reason": null, "id": "2ef47aee-8844-490c-804d-2a8efe561c65", "links": [ { "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65", "rel": "self" }, { "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65", "rel": "bookmark" } ], "name": "backup001", "object_count": 22, "size": 1, "status": "available", "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6" }, { "availability_zone": "az1", "container": "volumebackups", "created_at": "2013-04-02T10:21:48.000000",


71

"description": null, "fail_reason": null, "id": "4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8", "links": [ { "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8", "rel": "self" }, { "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/4dbf0ec2-0b57-4669-9823-9f7c76f2b4f8", "rel": "bookmark" } ], "name": "backup002", "object_count": 22, "size": 1, "status": "available", "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6" } ]}


72

Show backup details


GET /v2/{tenant_id}/backups/{backup_id}

Shows details for a specified backup.


Request

This table shows the URI parameters for the show backup details request:



{backup_id} UUID The unique identifier for a backup.


Response

Example 3.64. Show backup details: JSON response

{ "backup": { "availability_zone": "az1", "container": "volumebackups", "created_at": "2013-04-02T10:35:27.000000", "description": null, "fail_reason": null, "id": "2ef47aee-8844-490c-804d-2a8efe561c65", "links": [ { "href": "http://localhost:8776/v1/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65", "rel": "self" }, { "href": "http://localhost:8776/c95fc3e4afe248a49a28828f286a7b38/backups/2ef47aee-8844-490c-804d-2a8efe561c65", "rel": "bookmark" } ], "name": "backup001", "object_count": 22, "size": 1, "status": "available", "volume_id": "e5185058-943a-4cb4-96d9-72c184c337d6" }}


73

Delete backup


DELETE /v2/{tenant_id}/backups/{backup_id}

Deletes a specified backup.


Request

This table shows the URI parameters for the delete backup request:






74

Restore backup


POST /v2/{tenant_id}/backups/{backup_id}/restore

Restores a Block Storage backup to an existing or newBlock Storage volume.


Request

This table shows the URI parameters for the restore backup request:




Example 3.65. Restore backup: JSON request

{ "restore": { "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607" }}

Response

Example 3.66. Restore backup: JSON response

{ "restore": { "backup_id": "2ef47aee-8844-490c-804d-2a8efe561c65", "volume_id": "795114e8-7489-40be-a978-83797f2c1dd3" }}

Documents

Openstack Blockstorage API Ref