Storage resources

Storage resources are divided into two groups:

storage volumes, which can be attached to a running instance (accessible by the instance OS)
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).

Storage Volumes

A storage volume has

a capacity expressed in Gigabytes;
a created timestamp;
a realm_id specifying the realm in which the volume exists;
a state (for Amazon EC2 this is one of creating, available, in-use, deleting, deleted, error); and
a set of actions.

When attached to an instance, a storage volume will also expose a mount element which contains the attributes instance and device, specifying the instance, to which the volume is attached, and the mount point (e.g. /dev/sdh), respectively.

Get a list of all storage volumes

To list all storage volumes use call GET /api/storage_volumes.

Example request:

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

Server response:

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>

Get the details of a storage volume

To retrieve the details for the specified storage volume use call GET /api/storage_volumes/:id.

Example request:

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

Server response:

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>

Create a new storage volume

To create a new storage volume use call POST /api/storage_volumes. A client may specify a snapshot_id from which the storage volume is instantiated though this is optional. The capacity parameter, expressed in Gigabytes, is also optional and its default size is 1 GB. Finally clients may also specify the realm_id, as a storage volume can typically only be attached to instances running within the specified realm. If the realm is not specified it will set it at the first realm returned by the cloud provider. A successful operation will return HTTP 201 Created with the details of the new storage volume.

× Note:

Fujitsu GCP requires the size to be a multiple of 10, so the specified capacity is rounded up to the nearest multiple of ten, making the default size 10 GB.

As with the other POST operations in the Deltacloud API, clients may choose to specify operation parameters as multipart/form-data or as application/x-www-form-urlencoded data.

Example request:

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

Server response:

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>

Delete a storage volume

To delete the specified storage volume use call DELETE /api/storage_volumes/:id. The operation will return a HTTP 204 No Content after a succesful operation.

× Note:

The operation will fail if the given storage_volume is currently attached to an instance.

Example request:

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

Server response:

HTTP/1.1 204 No Content
Date: Thu, 28 Jul 2011 22:34:29 GMT

Example request: (error deleting a volume currently attached to an instance)

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

Server response:

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>

Attach a storage volume to a running instance

To attach the specified storage volume to a running instance use call POST /api/storage_volumes/:id/attach. Clients must specify the instance_id and the device 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 HTTP 202 Accepted after a succesful attach operation with details of the storage volume. In the example below, the state is reported as 'unknown' although the mount element is present. It is because 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.

Example request:

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

Server response:

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>

Detach a storage volume from an instance

To detach the given storage volume from the instance to which it is currently attached use call POST /api/storage_volumes/:id/detach. A succesful operation will return HTTP 201 Accepted with details of the storage volume. Similarly to attach operation, in the example below, the state is reported as 'unknown' and the mount element is still present as the processing has not been completed yet (hence the 202 status code).

Example request:

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

Server response:

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>

Storage snapshots

2015/07/20 - Apache Deltacloud has been retired.

For more information, please explore the Attic.