diff --git a/v2/src/openstack-blockstorage-devguide.xml b/v2/src/openstack-blockstorage-devguide.xml index c5867a1..7850729 100644 --- a/v2/src/openstack-blockstorage-devguide.xml +++ b/v2/src/openstack-blockstorage-devguide.xml @@ -60,7 +60,7 @@ format="SVG" scale="60"/> OpenStack Foundation API v2 - OpenStack Block Storage Service API v2 + OpenStack Block Storage Service @@ -71,12 +71,23 @@ format="SVG" scale="60"/> This document is for software developers who develop applications by using the OpenStack Block Storage Service - Application Programming Interface (API). - + Application Programming Interface + (API). + 2013-12-23 + + + + Updated API call descriptions to point to WADL + files. + + + + + 2013-12-14 @@ -98,7 +109,6 @@ format="SVG" scale="60"/> - 2013-04-21 @@ -110,7 +120,6 @@ format="SVG" scale="60"/> - 2013-04-10 @@ -134,15 +143,15 @@ format="SVG" scale="60"/> Preface - The OpenStack Block Storage project provides volume - management with the OpenStack Compute service. + OpenStack Block Storage provides volume management with the + OpenStack Compute service. This document describes the features available with the &API;. We welcome feedback, comments and bug reports at bugs.launchpad.net/Cinder.
- Intended Audience + Intended audience This guide assists software developers who develop applications by using the &API;. It assumes the reader has a general understanding of storage and is familiar with: @@ -158,19 +167,15 @@ format="SVG" scale="60"/>
- - -
- Additional Resources + 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. - + >www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
Glossary - To use the Block Storage API effectively, you should + To use the Block Storage API effectively, you must understand several key concepts: @@ -232,7 +237,6 @@ format="SVG" scale="60"/> 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, @@ -260,38 +264,33 @@ format="SVG" scale="60"/>
- -
- High-Level Task Flow - The high-level task flow for Block Storage is as - follows: - - - - The tenant creates a volume. - For example, the tenant creates a 30G volume called - vol1. - $ cinder create --display-name vol1 30 - - - This gives the tenant a volume id - 521752a6-acf6-4b2d-bc7a-119f9148cd8c. The tenant - attaches that volume to a virtual machine (VM) - 616fb98f-46ca-475e-917e-2563e5a8cd19: - For example - A:$ nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb - - - + High-level task flow + + To create and attach a volume + + 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. + + + 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 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb + +
- - General API Information + + General API information 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 @@ -301,35 +300,31 @@ format="SVG" scale="60"/> 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; send the token to a service. - - 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. - - - - Use the authentication token to send a GET to a - service you would like to use. - - - + get a token, and send the token to a service. + + + 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. + + + 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 @@ -344,7 +339,7 @@ format="SVG" scale="60"/>
- Request/Response Types + 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 @@ -361,8 +356,7 @@ format="SVG" scale="60"/> representation that can be used to efficiently determine when the state of services has changed. - - + @@ -392,16 +386,15 @@ format="SVG" scale="60"/> application/xml is requested via the Accept header: - Request with Headers (Getting Volume Types) + Request with headers: Get volume types GET /&VERSION;/441446/types HTTP/1.1 Host: dfw.blockstorage.api.openstackcloud.com X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb -Accept: application/xml +Accept: application/xml - Therefore an XML response format - is returned: + Therefore an XML response format is returned: - Response with Headers + Response with headers HTTP/1.1 200 OK Date: Fri, 20 Jul 2012 20:32:13 GMT Content-Length: 187 @@ -429,7 +422,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 reset after a certain amount of time passes. Absolute limits are fixed.
- Rate Limits + Rate limits Rate limits are specified in terms of both a human-readable wild-card URI and a machine-processable regular expression. The regular expression boundary matcher @@ -442,7 +435,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 for all API operations for all &GET;, &POST;, &PUT;, and &DELETE; calls for volumes:
Response FormatsResponse formats
Format
- + @@ -487,7 +480,8 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 Rate limits are applied in order relative to the verb, going from least to most specific. For example, although the threshold for &POST; to /v1.0/* is 10 per minute, one cannot - &POST; to /v1.0/* more than 50 times within a single day. + &POST; to /v1.0/* more than 50 times within a single + day.If you exceed the thresholds established for your account, a 413 (Rate Control) HTTP response will be returned with a Retry-After @@ -495,10 +489,10 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 again.
- Absolute Limits + Absolute limits The following table shows the absolute limits:
Default Rate LimitsDefault rate limits
Verb
- + @@ -512,7 +506,8 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 - + @@ -520,20 +515,21 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
- Date/Time Format + Date and time format The Block Storage Service uses an ISO-8601 compliant date - format for the display and consumption of date/time values. + format for the display and consumption of date time + values. - DB Service Date/Time Format + 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 + The following table describes the date time format codes:
Absolute LimitsAbsolute limits
Block StorageMaximum amount of block storage (in GBs)Maximum amount of block storage (in + GBs) 1 TB
- + @@ -555,7 +551,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 - + @@ -584,8 +580,8 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 FaultsWhen an error occurs, the Block Storage Service returns a fault object containing an HTTP error response code that - denotes the type of error. In the body of the response, the - system will return additional information about the fault. + 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. @@ -673,13 +669,13 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 errors when the server has erred or cannot perform the requested operation: - Example instanceFault Response: XML - + Example instanceFault response: XML + - Example Fault Response: JSON - + Example fault response: JSON + The error code (code) is returned in the body @@ -694,31 +690,30 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 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: + The following two badRequest examples show + errors when the volume size is invalid: - Example badRequest Fault on Volume Size Errors: + <title>Example badRequest fault on volume size errors: XML - + - Example badRequest Fault on Volume Size Errors: + <title>Example badRequest fault on volume size errors: JSON - + The next two examples show itemNotFound errors: - Example itemNotFound Fault: XML - + Example itemNotFound fault: XML + - Example itemNotFound Fault: JSON - + Example itemNotFound fault: JSON + @@ -727,607 +722,166 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7 xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml"> - API Operations + API operations
Volumes A volume is 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. - When making an API call to - create, list, or delete volume(s), the following status values - are possible: - - - 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 has occurred with the - volume. - - - ERROR_DELETING – There was an error deleting the - volume. - - - BACKING-UP – The volume is being backed - up. - - - RESTORING-BACKUP – A backup is being restored to - the volume. - - - ERROR_RESTORING – There was an error restoring a - backup to the volume. - - - -
- - + When you create, list, or delete volumes, these status + values are possible: + - - - - + + + - - - + + - - - + + - - - + + - - - + + - - - + + + + + + + + + + + + + + + + + + + + + + -
- Create Volume - -
- - - - - - - - - - - - - - - - - - - Create Volumes: JSON Request - POST /&VERSION;/volumes -Content-Type: application/json -Accept: application/json - - - - Create Volumes: JSON Response - - - Returns status code 200 on - success. - -
- List Volumes - -
- - - - - - - - - - - - - - - - - - - List Volumes: JSON Request - GET /&VERSION;/volumes -Accept: application/json - - - List Volumes: JSON Response - - - Returns status code 200 on - success. - -
- List Volume Details - -
- - - - - - - - - - - - - - - - - - - List Volume Details: JSON Request - GET /&VERSION;/volumes/details -Accept: application/json - - - List Volume Details: JSON Response - - - Returns status code 200 on - success. - -
- Show Volume - -
- - - - - - - - - - - - - - - - - - - Show Volume: JSON Request - GET /&VERSION;/volumes/5aa119a8-d25b-45a7-8d1b-88e127885635 -Accept: application/json - - - Show Volume: JSON Response - - - Returns status code 200 on - success. - -
- Update Volume - -
- - - - - - - - - - - - - - - - - - - Update Volume: JSON Request - PUT /&VERSION;/volumes5aa119a8-d25b-45a7-8d1b-88e127885635 -Content-Type: application/json -Accept: application/json - - - - Update Volume: JSON Response - - - Returns status code 200 on - success. - -
- Delete Volume - -
- - - - - - - - - - - - - - - - - - - Delete Volume: Request - DELETE /&VERSION;/volumes/521752a6-acf6-4b2d-bc7a-119f9148cd8c - - - Delete Volume: Response - The response body is empty with status code 202. - - - You cannot delete a volume if it has snapshots - associated with it. - - + + + + + + + + + + + + + +
Snapshots - A snapshot is a point in time - copy of the data contained in a volume. - When making an API call to create, list, or delete - snapshot(s), the following status values are possible: - - - CREATING – The snapshot is being created. - - - AVAILABLE – The snapshot is ready to be - used. - - - DELETING – The snapshot is being deleted. - - - ERROR – An error occurred with the - snapshot. - - - ERROR_DELETING – There was an error deleting the - snapshot. - - -
- Create Snapshot - -
- - - - - - - - - - - - - - - - - - - Create Snapshot: JSON Request - POST /&VERSION;/snapshots -Content-Type: application/json -Accept: application/json - - - - Create Snapshot: JSON Response - - - Returns status code 202 on success - -
- List Snapshots - -
- - - - - - - - - - - - - - - - - - - List Snapshots: JSON Request - GET /&VERSION;/snapshots -Accept: application/json - - - List Snapshots: JSON Response - - - Returns status code 200 on - success. - -
- List Snapshot Details - -
- - - - - - - - - - - - - - - - - - - List Snapshots Details: JSON Request - GET /&VERSION;/snapshots/details -Accept: application/json - - - List Snapshots Details: JSON Response - - - Returns status code 200 on - success. - -
- Show Snapshot - -
- - - - - - - - - - - - - - - - - - - Show Snapshot: JSON Request - GET /&VERSION;/snapshots//2bb856e1-b3d8-4432-a858-09e4ce939389 -Accept: application/json - - - Show Snapshot: JSON Response - - - Returns status code 200 on - success. - -
- Update Snapshot - -
- - - - - - - - - - - - - - - - - - - Update Snapshot: JSON Request - PUT /&VERSION;/snapshots/2402b902-0b7a-458c-9c07-7435a826f794 -Content-Type: application/json -Accept: application/json - - - - Update Snapshot: JSON Response - - - Returns status code 200 on - success. - -
- Delete Snapshot - -
- - - - - - - - - - - - - - - - - - - Delete Snapshot: Request - DELETE /&VERSION;/snapshots/3fbbcccf-d058-4502-8844-6feeffdf4cb5 - - - Delete Snapshot: Response - The response body is empty with status code 202. - - + 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
- Volume Types -
- List Volume Types - -
- - - - - - - - - - - - - - - - - - - List Volume Types: JSON Request - GET /&VERSION;/types -Accept: application/json - - - List Volume Types: JSON Response - - - Returns status code 200 on - success. - -
- Show Volume Type - -
- - - - - - - - - - - - - - - - - - - Show Volume Type: JSON Request - GET /&VERSION;/types/6685584b-1eac-4da6-b5c3-555430cf68ff -Accept: application/json - - - Show Volume Type: JSON Response - - - Returns status code 200 on - success. - + Volume types + + + + + + + +
Extensions - The Block Storage API is extensible. Extensions are + You can extend the Block Storage API. Extensions are add-ons to the API that enable new features.
Backups @@ -1336,36 +890,60 @@ Accept: application/json 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. Backup and restore operations can only + 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 making an API call to - create, list, or delete backup(s), the following status + When you create, list, or delete backups, these status values are possible: - - - 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 – There was an error restoring - a backup to the volume. - - + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + In the event of an error, more information about the error can be found in the FAIL_REASON field for the backup. @@ -1419,7 +997,7 @@ Accept: application/json
- Create Backup + Create backup
@@ -1440,20 +1018,20 @@ Accept: application/json - Create Backup: JSON Request + Create backup request: JSON POST /&VERSION;/backups Content-Type: application/json -Accept: application/json +Accept: application/json - Create Backup: JSON Response + Create backup response: JSON Returns status code 202 on success
- List Backups + List backups
@@ -1470,24 +1048,24 @@ Accept: application/json + tenant who submits the request can access. - List Backups: JSON Request + List backups request: JSON GET /&VERSION;/backups -Accept: application/json +Accept: application/json - List Backups: JSON Response + List backups response: JSON Returns status code 200 on success.
- List Backup Details + List backup details
@@ -1505,24 +1083,24 @@ Accept: application/json + request can access. - List Backups: JSON Request + List backups request: JSON GET /&VERSION;/backups/details -Accept: application/json +Accept: application/json - List Backups: JSON Response + List backups response: JSON Returns status code 200 on success.
- Show Backup + Show backup
@@ -1539,24 +1117,24 @@ Accept: application/json + ID. - Show Backup: JSON Request + Show backup request: JSON GET /&VERSION;/backups/fa4351c8-d881-4e31-904f-c28a8a2e80cc Accept: application/json - Show Backup: JSON Response + Show backup response: JSON Returns status code 200 on success.
- Delete Backup + Delete backup
@@ -1577,16 +1155,16 @@ Accept: application/json - Delete Backup: Request - DELETE /&VERSION;/backups/fa4351c8-d881-4e31-904f-c28a8a2e80cc + Delete backup: Request + DELETE /&VERSION;/backups/fa4351c8-d881-4e31-904f-c28a8a2e80cc - Delete Backup: Response - The response body is empty with status code 202. + Delete backup: Response + The response body is empty with status code 202.
- Restore Backup + Restore backup
@@ -1603,19 +1181,19 @@ Accept: application/json + new Block Storage volume. - Restore Backup: JSON Request + Restore backup request: JSON POST /&VERSION;/backups/fa4351c8-d881-4e31-904f-c28a8a2e80cc/restore Content-Type: application/json -Accept: application/json +Accept: application/json - Restore Backup: JSON Response + Restore backup response: JSON Returns status code 202 on
Date/Time Format CodesDate time format codes
Code
TSeparator for date/timeSeparator for date time
HH
VerbURIDescription
StatusDescription
&GET;/volumesLists a summary of all volumes defined in Block - Storage that the tenant who submits the request can - access.CREATINGThe volume is being created. +
&GET;/volumes/volume_idLists detailed information for a specified - volume.AVAILABLEThe volume is ready to be attached to an + instance. +
&POST;/volumesCreates a Block Storage volume.ATTACHINGThe volume is attaching to an instance. +
&PUT;/volumes/volume_idUpdates a specified volume.IN-USEThe volume is attached to an instance. +
&DELETE;/volumes/volume_idDeletes a specified volume.DELETINGThe volume is being deleted. +
ERRORAn error has occurred with the volume. +
ERROR_DELETINGThere was an error deleting the volume. +
BACKING-UPThe volume is being backed up. +
RESTORING-BACKUPA backup is being restored to the volume. +
ERROR_RESTORINGThere was an error restoring a backup to the + volume. +
VerbURIDescription
&POST;/volumesCreates a volume.
VerbURIDescription
&GET;/volumesLists volumes defined in Block Storage that the - tenant who submits the request can access.
VerbURIDescription
&GET;/volumes/detailsLists detailed information for Block Storage volumes - that the tenant who submits the request can access. -
VerbURIDescription
&GET;/volumes/volume-idLists detailed information for the specified volume - ID.
VerbURIDescription
&PUT;/volumes/volume-idUpdates a specified volume.
VerbURIDescription
&DELETE;/volumes/volume-idDeletes the specified volume.
VerbURIDescription
&POST;/snapshotsCreates a snapshot from a specified volume.
VerbURIDescription
&GET;/snapshotsLists snapshots defined in Block Storage that the - tenant who submits the request can access.
VerbURIDescription
&GET;/snapshots/detailsLists detailed information for snapshots defined in - Block Storage that the tenant who submits the request - can access.
VerbURIDescription
&GET;/snapshots/snapshot-idLists detailed information for a specified snapshot - ID.
VerbURIDescription
&PUT;/snapshots/snapshot-idUpdates a specified snapshot.
VerbURIDescription
&DELETE;/snapshots/snapshot-idDeletes a specified snapshot.
StatusDescription
+ CREATINGThe snapshot is being created. +
+ AVAILABLEThe snapshot is ready to be used. +
+ DELETINGThe snapshot is being deleted. +
+ ERRORAn error occurred with the snapshot. +
+ ERROR_DELETINGThere was an error deleting the snapshot. +
VerbURIDescription
&GET;/typesLists volume types and their information.
VerbURIDescription
&GET;/types/type-idShows information about a specified volume - type.
StatusDescription
+ CREATINGThe backup is being created. +
+ AVAILABLEThe backup is ready to be restored to a + volume. +
+ DELETINGThe backup is being deleted. +
+ ERRORAn error has occurred with the backup. +
+ RESTORINGThe backup is being restored to a + volume. +
+ ERROR_RESTORINGThere was an error restoring a backup to the + volume. +
&GET; /backups Lists backups defined in Block Storage that the - tenant who submits the request can access.
/backups/details Lists detailed information for backups defined in Block Storage that the tenant who submits the - request can access.
&GET; /backups/backup-id Lists detailed information for a specified backup - ID.
&POST; /backups/backup_id/restore Restores a Block Storage backup to an existing or - new Block Storage volume..