| --- |
| site_name: Deltacloud API |
| title: Storage resources |
| --- |
| |
| <br/> |
| |
| <div class="alert alert-info"> |
| <a class="close" data-dismiss="alert" href="#">×</a> |
| This section is currently being updated. |
| </div> |
| |
| <div class="row"> |
| <div class="span8"> |
| |
| <h3 id="resources">Storage resources</h3> |
| |
| <p> |
| Storage resources are divided into two groups: storage volumes can be attached to a running instance (accessible by the instance OS), and blob storage which represents a generic 'key <−−> value' based data store, as implemented by Rackspace CloudFiles or Amazon S3. Storage snapshots represent a storage volume, a backup which is created at a particular point of time (a snapshot). |
| </p> |
| |
| <h3 id="volumes">Storage Volumes</h3> |
| |
| <p style="margin-bottom:0px"> |
| A storage_volume has a <strong>capacity</strong> expressed in Gigabytes, a <strong>created</strong> timestamp, a <strong>realm_id</strong> specifying the realm in which the volume exists, a <strong>state</strong> (for Amazon EC2 this is one of creating | available | in-use | deleting | deleted | error) and a set of <strong>actions</strong>. When attached to an instance, a storage_volume will also expose a <strong>mount</strong> element |
| </p> |
| |
| </div> |
| <div class="span4"> |
| |
| <ul class="nav nav-list well"> |
| <li class="nav-header"> |
| REST API |
| </li> |
| <li><a href="/rest-api.html">Introduction</a></li> |
| <li><a href="/api-entry-point.html">API entry point</a></li> |
| <li><a href="/compute-resources.html">Compute resources</a></li> |
| <li class="active"><a href="#resources">Storage resources</a></li> |
| <ul class="nav nav-list"> |
| <li><a href="#volumes">Storage volumes</a></li> |
| <li><a href="/storage-snapshots.html">Storage snaphots</a></li> |
| <li><a href="/blob-storage.html">Blob storage</a></li> |
| </ul> |
| </ul> |
| |
| </div> |
| </div> |
| |
| |
| <p style="margin-top:0px"> |
| which contains the attributes <strong>instance </strong>and <strong>device</strong>, specifying the instance to which the volume is attached and the mount point (e.g. /dev/sdh), respectively. |
| </p> |
| |
| <h4>Get a list of all storage volumes</h4> |
| |
| <p> |
| To list all storage volumes use call <strong>GET /api/storage_volumes</strong>. |
| </p> |
| |
| <p> |
| Example request: |
| </p> |
| |
| <pre> |
| GET /api/storage_volumes?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 200 OK |
| Content-Type: application/xml |
| Date: Thu, 28 Jul 2011 21:04:09 GMT |
| Content-Length: 1341 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <storage_volumes> |
| <storage_volume href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' id='vol-0bc0de60'> |
| <created>Thu Jul 28 20:44:18 UTC 2011</created> |
| <capacity unit='GB'>10</capacity> |
| <realm_id>us-east-1c</realm_id> |
| <state>AVAILABLE</state> |
| <actions> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach' method='post' rel='attach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach' method='post' rel='detach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' method='delete' rel='destroy' /> |
| </actions> |
| </storage_volume> |
| <storage_volume href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2' id='vol-99fbe5f2'> |
| <created>Thu Jul 28 20:56:07 UTC 2011</created> |
| <capacity unit='GB'>15</capacity> |
| <realm_id>us-east-1c</realm_id> |
| <state>AVAILABLE</state> |
| <actions> |
| <link href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2/attach' method='post' rel='attach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2/detach' method='post' rel='detach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2' method='delete' rel='destroy' /> |
| </actions> |
| </storage_volume> |
| </storage_volumes> |
| </pre> |
| |
| <h4>Get the details for a storage volume</h4> |
| |
| <p> |
| To retrieve the details for the specified storage_volume use call <strong>GET /api/storage_volumes/:id</strong>. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| GET /api/storage_volumes/vol-99fbe5f2?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 200 OK |
| Content-Type: application/xml |
| Date: Thu, 28 Jul 2011 21:06:39 GMT |
| Content-Length: 794 |
| <?xml version='1.0' encoding='utf-8' ?> |
| <storage_volume href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2' id='vol-99fbe5f2'> |
| <created>Thu Jul 28 20:56:07 UTC 2011</created> |
| <capacity unit='GB'>15</capacity> |
| <realm_id>us-east-1c</realm_id> |
| <state>IN-USE</state> |
| <mount> |
| <instance href='i-b100b3d0' id='i-b100b3d0'></instance> |
| <device name='/dev/sdh'></device> |
| </mount> |
| <actions> |
| <link href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2/attach' method='post' rel='attach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2/detach' method='post' rel='detach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2' method='delete' rel='destroy' /> |
| </actions> |
| </storage_volume> |
| </pre> |
| |
| <h4>Create a new storage volume</h4> |
| |
| <p> |
| To create a new storage_volume use call <strong>POST /api/storage_volumes</strong>. A client may specify a <strong>snapshot_id</strong> from which to instantiate the storage_volume though this is optional. The <strong>capacity</strong> parameter, expressed in Gigabytes, is also optional and will default to 1 Gigabyte. Finally clients may also specify the <strong>realm_id</strong> as a storage_volume can typically only be attached to instances running within the specified realm. If the realm is not specified it will default to the first realm returned by the cloud provider. A succesful operation will return <strong>HTTP 201 Created</strong> with the details of the newly created storage_volume. |
| </p> |
| |
| <p> |
| As with the other <strong>POST</strong> operations in the Deltacloud API, clients may choose to specify operation parameters as multipart/form-data or as application/x-www-form-urlencoded data. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| POST /api/storage_volumes?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| Content-Length: 31 |
| Content-Type: application/x-www-form-urlencoded |
| |
| capacity=10&realm_id=us-east-1c |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 201 Created |
| Date: Thu, 28 Jul 2011 20:44:27 GMT |
| Content-Length: 649 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <storage_volume href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' id='vol-0bc0de60'> |
| <created>Thu Jul 28 20:44:18 UTC 2011</created> |
| <capacity unit='GB'>10</capacity> |
| <realm_id>us-east-1c</realm_id> |
| <state>CREATING</state> |
| <actions> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach' method='post' rel='attach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach' method='post' rel='detach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' method='delete' rel='destroy' /> |
| </actions> |
| </storage_volume> |
| </pre> |
| |
| <h4>Delete a storage volume</h4> |
| |
| <p> |
| To delete the specified storage_volume use call <strong>DELETE /api/storage_volumes/:id</strong>. The operation will return a <strong>HTTP 204 No Content</strong> after a succesful operation. Note that the operation will fail if the given storage_volume is currently attached to an instance. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| DELETE /api/storage_volumes/vol-0bc0de60?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 204 No Content |
| Date: Thu, 28 Jul 2011 22:34:29 GMT |
| </pre> |
| |
| <p>Example request: (error deleting a volume currently attached to an instance)</p> |
| |
| <pre> |
| DELETE /api/storage_volumes/vol-0bc0de60?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 502 Bad Gateway |
| Content-Type: application/xml |
| Date: Thu, 28 Jul 2011 22:30:07 GMT |
| Content-Length: 617 |
| |
| <error status='502' url='/api/storage_volumes/vol-0bc0de60?format=xml'> |
| <kind>backend_error</kind> |
| <backend driver='ec2'> |
| <code>502</code> |
| </backend> |
| <message><![CDATA[Client.VolumeInUse: Volume vol-0bc0de60 is currently attached to i-b100b3d0 |
| REQUEST=ec2.us-east-1.amazonaws.com:443/?AWSAccessKeyId=AKIAJATNOR5HKG3FK27Q&Action=DeleteVolume&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2011-07-28T22%3A30%3A00.000Z&Version=2010-08-31&VolumeId=vol-0bc0de60&Signature=WnZTd9vFaUZEwfuifyo3%2FWa2HBEG1S7R8Iv%2FHqc%2BmqE%3D |
| REQUEST ID=5dff67bb-d63a-4055-b550-f323fa16e185]]></message> |
| </error> |
| </pre> |
| |
| <h4>Attach a storage volume to a running instance</h4> |
| |
| <p> |
| To attach the specified storage_volume to a running instance use call <strong>POST /api/storage_volumes/:id/attach</strong>. Clients must specify the <strong>instance_id</strong> and the <strong>device</strong> as parameters. The device parameter is used as the 'mount point', that is, the location at which the storage_volume will be exposed to the given instance (e.g., /dev/sdh). The Deltacloud server will respond with a <strong>HTTP 202 Accepted</strong> after a succesful attach operation together with details of the storage_volume. Note in the example below that the state is reported as 'unknown' although the <strong>mount</strong> element is present, as the processing has not yet been completed (hence the 202 status code). Clients may specify the required parameters as multipart/form-data or as application/x-www-form-urlencoded data. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| POST /api/storage_volumes/vol-0bc0de60/attach?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| Content-Length: 38 |
| Content-Type: application/x-www-form-urlencoded |
| |
| instance_id=i-b100b3d0&device=/dev/sdi |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 202 Accepted |
| Date: Thu, 28 Jul 2011 21:36:17 GMT |
| Content-Length: 709 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <storage_volume href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' id='vol-0bc0de60'> |
| <capacity unit='GB'></capacity> |
| <device>/dev/sdi</device> |
| <state>unknown</state> |
| <mount> |
| <instance href='i-b100b3d0' id='i-b100b3d0'></instance> |
| <device name='/dev/sdi'></device> |
| </mount> |
| <actions> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach' method='post' rel='attach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach' method='post' rel='detach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' method='delete' rel='destroy' /> |
| </actions> |
| </storage_volume> |
| </pre> |
| |
| <h4>Detach a storage volume from an instance</h4> |
| |
| <p> |
| To detache the given storage_volume from the instance to which it is currently attached use call <strong>POST /api/storage_volumes/:id/detach</strong>. A succesful operation will return <strong>HTTP 201 Accepted</strong> together with details of the storage_volume. Note in the example that like the attach operation above, <strong>state</strong> is reported as 'unknown' and the <strong>mount</strong> element is still present as the processing has not yet been completed (hence the 202 status code). |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| POST /api/storage_volumes/vol-0bc0de60/detach?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 202 Accepted |
| Content-Type: application/xml |
| Date: Thu, 28 Jul 2011 21:29:18 GMT |
| Content-Length: 709 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <storage_volume href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' id='vol-0bc0de60'> |
| <capacity unit='GB'></capacity> |
| <device>/dev/sdi</device> |
| <state>unknown</state> |
| <mount> |
| <instance href='i-b100b3d0' id='i-b100b3d0'></instance> |
| <device name='/dev/sdi'></device> |
| </mount> |
| <actions> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach' method='post' rel='attach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach' method='post' rel='detach' /> |
| <link href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' method='delete' rel='destroy' /> |
| </actions> |
| </storage_volume> |
| </pre> |
| |
| <a class="btn btn-inverse btn-large" style="float: right" href="/storage-snapshots.html">Storage snapshots <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a> |
| |
| <br/> |
| |
