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

For more information, please explore the Attic.

Deltacloud API


Instances

An instance represents the core of all cloud compute activity: a running virtual machine. An instance is created from an image, with a specified hardware profile and in a given realm. Each instance can have a number of other attributes, not all of which are exposed for all back-end cloud providers. The full list of possible instance attributes is:

Attribute Meaning
owner_id the id of the cloud provider account that launched the instance
image_id the id of the image from which the instance was launched
name a human readable name for the instance given at launch time
realm_id realm into which the instance was launched
state current state of the instance (e.g. 'running')
actions actions that a client may effect on the instance, based on current state
public_addresses the globally routable IP address of the instance
private_addresses the private IP address of the instance, routable within its private network
instance_profile the specific values of memory, cpu, storage
launch_time timestamp at which the instance was launched
keyname name of authentication key, if this method is used for authentication (e.g. EC2)
username the username for authentication when connecting to the instance
password the password used together with username above
firewalls the firewalls that this instance was launched into (EC2 specific)

Get a list of all current instances

To produce a list of all current instances in the given cloud (belonging to the specified account) use call GET /api/instances. The example below displays instances in the Amazon EC2 cloud.

Example request: 

GET /api/instances?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*

Client response:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 2790
<?xml version='1.0' encoding='utf-8' ?>
<instances>
  <instance href='http://localhost:3001/api/instances/i-1fbc627e' id='i-1fbc627e'>
    <name>ami-f51aff9c</name>
    <owner_id>393485797142</owner_id>
    <image href='http://localhost:3001/api/images/ami-f51aff9c' id='ami-f51aff9c'></image>
    <realm href='http://localhost:3001/api/realms/us-east-1c' id='us-east-1c'></realm>
    <state>RUNNING</state>
    <hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.medium' id='c1.medium'>
    </hardware_profile>
    <actions>
      <link href='http://localhost:3001/api/instances/i-1fbc627e/reboot' method='post' rel='reboot' />
      <link href='http://localhost:3001/api/instances/i-1fbc627e/stop' method='post' rel='stop' />
      <link href='http://localhost:3001/api/instances/i-1fbc627e/run;id=i-1fbc627e' method='post' rel='run' />
    </actions>
    <launch_time>2011-07-22T11:29:48.000Z</launch_time>
    <public_addresses><address>ec2-50-16-183-107.compute-1.amazonaws.com</address></public_addresses>
    <private_addresses><address>domU-12-31-39-0F-79-D4.compute-1.internal</address></private_addresses>
    <firewalls>
      <firewall href='http://localhost:3001/api/firewalls/default' id='default'></firewall>
    </firewalls>
    <authentication type='key'>
      <login>
        <keyname>eftah</keyname>
      </login>
    </authentication>
  </instance>
  <instance href='http://localhost:3001/api/instances/i-f3ba6492' id='i-f3ba6492'>
    <name>ami-2b5fba42</name>
    <owner_id>393485797142</owner_id>
    <image href='http://localhost:3001/api/images/ami-2b5fba42' id='ami-2b5fba42'></image>
    <realm href='http://localhost:3001/api/realms/us-east-1d' id='us-east-1d'></realm>
    <state>RUNNING</state>
    <hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.small' id='m1.small'>
    </hardware_profile>
    <actions>
      <link href='http://localhost:3001/api/instances/i-f3ba6492/reboot' method='post' rel='reboot' />
      <link href='http://localhost:3001/api/instances/i-f3ba6492/stop' method='post' rel='stop' />
      <link href='http://localhost:3001/api/instances/i-f3ba6492/run;id=i-f3ba6492' method='post' rel='run' />
    </actions>
    <launch_time>2011-07-22T11:32:25.000Z</launch_time>
    <public_addresses><address>ec2-184-73-78-87.compute-1.amazonaws.com</address></public_addresses>
    <private_addresses><address>ip-10-196-89-221.ec2.internal</address></private_addresses>
    <firewalls>
      <firewall href='http://localhost:3001/api/firewalls/default' id='default'></firewall>
      <firewall href='http://localhost:3001/api/firewalls/test' id='test'></firewall>
    </firewalls>
    <authentication type='key'>
      <login>
        <keyname>eftah</keyname>
      </login>
    </authentication>
  </instance>
</instances>

Get the details of an instance

To get the details of a specific instance use call GET /api/instances/:id. The example below shows an instance launched in the Rackspace Cloudservers cloud. As you can see, the type of authentication is password but the username and password attributes are blank. The reason why these attributes are blank is that Rackspace only reports these values once, during instance creation and not for subsequent requests. To find an example of the response from an instance go to the Create an instance section.

Example request:

GET /api/instances/20112212?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*

Server response:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1167
<?xml version='1.0' encoding='utf-8' ?>
<instance href='http://localhost:3002/api/instances/20112212' id='20112212'>
  <name>myserver</name>
  <owner_id>mandreou</owner_id>
  <image href='http://localhost:3002/api/images/53' id='53'></image>
  <realm href='http://localhost:3002/api/realms/us' id='us'></realm>
  <state>RUNNING</state>
  <hardware_profile href='http://localhost:3002/api/hardware_profiles/1' id='1'>
  </hardware_profile>
  <actions>
    <link href='http://localhost:3002/api/instances/20112212/reboot' method='post' rel='reboot' />
    <link href='http://localhost:3002/api/instances/20112212/stop' method='post' rel='stop' />
    <link href='http://localhost:3002/api/instances/20112212/run;id=20112212' method='post' rel='run' />
    <link href='http://localhost:3002/api/images;instance_id=20112212' method='post' rel='create_image' />
  </actions>
  <public_addresses><address>50.57.116.72</address></public_addresses>
  <private_addresses><address>10.182.143.64</address></private_addresses>
  <authentication type='password'>
    <login>
      <username>root</username>
      <password></password>
    </login>
  </authentication>
</instance>

Launch an action on an instance

To launch an action on an instance use call POST /api/instances/:id/:action. The valid actions for an instance are specified by the instance states entity. The set of permissible actions that a client may perform on an instance at a given time depends on the current instance state. These are reported by the <actions> attribute in the Deltacloud server response to the GET /api/instances/:id call (Get the details of an instance section). The first example below shows a reboot action on a currently running instance, followed by a stop action.

After invoking the stop operation, the instance state may still be reported as RUNNING in the Deltacloud server response. It is because it may take some time for the instance state to change in the back-end cloud provider (and this will vary between providers). You can assure yourself that the action was performed correctly by requesting a list of instances or a by requesting a specific instance.

The Deltacloud server also allows a special 'run-on-instance' action for some cloud provider instances.This enables a client to perform a command on a running instance over SSH. The Deltacloud server will return the output of that command to the client. This is reported as the run action in the list of instance actions, if it is available. The cmd parameter specifies the command, which is executed on a running instance.The private_key parameter specifies the authentication for cloud providers that expect key based authentication for connecting to instances . For those cloud providers that use username/password for authentication, the password parameter specifies the authentication. Examples below illustrate the run-on-instance feature for an Amazon EC2 instance and a Rackspace Cloudservers instance. The examples differ in how authentication is performed (private RSA Key for EC2 and username/password for Rackspace).

Example request (reboot):

POST /api/instances/i-f3ba6492/reboot?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
Content-Length: 1322

<?xml version='1.0' encoding='utf-8' ?>
<instance href='http://localhost:3001/api/instances/i-f3ba6492' id='i-f3ba6492'>
  <name>ami-f51aff9c</name>
  <owner_id>393485797142</owner_id>
  <image href='http://localhost:3001/api/images/ami-f51aff9c' id='ami-f51aff9c'></image>
  <realm href='http://localhost:3001/api/realms/us-east-1c' id='us-east-1c'></realm>
  <state>RUNNING</state>
  <hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.medium' id='c1.medium'>
  </hardware_profile>
  <actions>
    <link href='http://localhost:3001/api/instances/i-f3ba6492/reboot' method='post' rel='reboot' />
    <link href='http://localhost:3001/api/instances/i-f3ba6492/stop' method='post' rel='stop' />
    <link href='http://localhost:3001/api/instances/i-f3ba6492/run;id=i-f3ba6492' method='post' rel='run' />
  </actions>
  <launch_time>2011-07-22T11:29:48.000Z</launch_time>
  <public_addresses><address>ec2-50-16-183-107.compute-1.amazonaws.com</address></public_addresses>
  <private_addresses><address>domU-12-31-39-0F-79-D4.compute-1.internal</address></private_addresses>
  <firewalls>  <firewall href='http://localhost:3001/api/firewalls/default' id='default'></firewall></firewalls>
  <authentication type='key'>
    <login>
      <keyname>eftah</keyname>
    </login>
  </authentication>
</instance>

Example request (stop):

POST /api/instances/20112212/stop?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*

Server response:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1167

<?xml version='1.0' encoding='utf-8' ?>
<instance href='http://localhost:3002/api/instances/20112212' id='20112212'>
  <name>myserver</name>
  <owner_id>mandreou</owner_id>
  <image href='http://localhost:3002/api/images/53' id='53'></image>
  <realm href='http://localhost:3002/api/realms/us' id='us'></realm>
  <state>STOPPED</state>
  <hardware_profile href='http://localhost:3002/api/hardware_profiles/1' id='1'>
  </hardware_profile>
  <actions>
    <link href='http://localhost:3002/api/instances/20112212/reboot' method='post' rel='reboot' />
    <link href='http://localhost:3002/api/instances/20112212/stop' method='post' rel='stop' />
    <link href='http://localhost:3002/api/instances/20112212/run;id=20112212' method='post' rel='run' />
    <link href='http://localhost:3002/api/images;instance_id=20112212' method='post' rel='create_image' />
  </actions>
  <public_addresses><address>50.57.116.72</address></public_addresses>
  <private_addresses><address>10.182.143.64</address></private_addresses>
  <authentication type='password'>
    <login>
      <username>root</username>
      <password></password>
    </login>
  </authentication>
</instance>

Example request (run-on-instance Amazon EC2):

× Note:

Run-on-instance requests to EC2 instances will fail with 502 Bad Gateway - Execution Expired if the firewall in which the instance was launched does not grant SSH access (tcp, port 22) to the requesting client's IP address. This access may be given using the firewalls collection.

POST /api/instances/i-afde73ce/run?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Content-Length: 1927
Content-Type: multipart/form-data; boundary=----------------------------332ed6691ab8

------------------------------332ed6691ab8
Content-Disposition: form-data; name="cmd"

uname -a; ls -l
------------------------------332ed6691ab8
Content-Disposition: form-data; name="private_key"

-----BEGIN RSA PRIVATE KEY-----.BTTEpATBAAKDAQEA4t3R/PgUo3KDDuX4
vZZpZuXFkAA/5X2lFRY2/xsQqbPz9utPOsUoPf9Aajy+.vGRJrO2KAJ9U/JTNDzr
3NPbG3aHYPSnwsSxkFSG4Q6ukqYlxT9TPF/+wvdxfAtp3nYw3ZGuSX/DOtToWtQ8
F/+GvHTHKDQSB+TeEs1Sa/PFwxpspB+RqHbqOTWPsFOHL+9sZGTqd6D4B.R6DBNh
9Dabu9BVZrl5BTOKlbAgrKnzsGKvaBST/D2.AB/HB9/GOT36OoBmEr1y9gFwu4Xf
aKw+AXVf9y9TKxVD3TE5uB.oDZG8s4gr2e691xHG9YGzBBBbNzfFh94b3Td5JBGS
zRDTKYBfOgv+Zu5N+WyeaZ0ab50DwK9BXYB5hsRu5zbAqObbTZkwN9qwBOZHzATX
wVTZU+eTz.39OZPqu4fQwrBN13lDbUoZxlqT9g2+haQBB9sTDzQEZ08QKBgQDJyw
lBBZqQKBgQDz5E2rL59lNS5pBxDO9r6B9rXtBBTZ5tZUWNFRvyNsxY5nJT03.KDw
qo2VP5WDZeOhRWEUY96./pWN3hNFDkT44vDpeXQUh3rBHyD5DWvWxAze9Ds+UTO/
esuLwP5vXhfoYp6gV9XG.BEBzSVq8kZ2kZtlbWHTR/SGepTkDgYEA9zwHTDhtKR2
KS8/BSFZQ884ZqFkbwT9fTW6s0rgUSBDTUDgYEA9W5HXTOEPGFDnqBhKPLN.xD9D
vZZpZuXFkAA/5X2lFRY2/xsQqbPz9utPOsUoPf9Aajy+.vGRJrO2KAJ9U/JTNDzr
lBBZqQKBgQDz5E2rL59lNS5pBxDO9r6B9rXtBBTZ5tZUWNFRvyNsxY5nJT03.KDw
F/+GvHTHKDQSB+TeEs1Sa/PFwxpspB+RqHbqOTWPsFOHL+9sZGTqd6D4B.R6DBNh
wVTZU+eTz.39OZPqu4fQwrBN13lDbUoZxlqT9g2+haQBB9sTDzQEZ08QKBgQDJyw
lBBZqQKBgQDz5E2rL59lNS5pBxDO9r6B9rXtBBTZ5tZUWNFRvyNsxY5nJT03.KDw
DAAeVWKU1OyDXfN4v6Zn1nNrhSkdrd+XV0nTLExsfg==.-----END RSA PRIVAT
E KEY-----
------------------------------332ed6691ab8--

Server response:

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Mon, 25 Jul 2011 12:56:02 GMT
Content-Length: 497

<instance href='http://localhost:3001/api/instances/i-afde73ce' id='i-afde73ce'>
  <public_address>
    ec2-50-19-59-126.compute-1.amazonaws.com
  </public_address>
  <command>
    uname -a; ls -l
  </command>
  <output>Linux domU-12-31-39-0F-E1-78 2.6.21.7-2.fc8xen #1 SMP Fri Feb 15 12:39:36 EST 2008 i686 i686 i386 GNU/Linux
  total 140
  -rw-r--r-- 1 root root 137263 Mar 26  2008 ec2-ami-tools-1.3-19974.noarch.rpm
  -rw-r--r-- 1 root root      0 Mar 26  2008 firstlogin
  </output>
</instance>

Example request (run-on-instance Rackspace Cloudservers):

POST /api/instances/20117112/run?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
Content-Length: 275
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------9b05ece66f4d
------------------------------9b05ece66f4d
Content-Disposition: form-data; name="cmd"

uname -a; ifconfig; pwd
------------------------------9b05ece66f4d
Content-Disposition: form-data; name="password"

myserverqB2Uwk21I
------------------------------9b05ece66f4d--

Server response:

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Mon, 25 Jul 2011 13:02:15 GMT
Content-Length: 1781

<instance href='http://localhost:3002/api/instances/20117112' id='20117112'>
  <public_address>
    50.57.117.249
  </public_address>
  <command>
    uname -a; ifconfig; pwd
  </command>
  <output>Linux myserver 2.6.35.4-rscloud #8 SMP Mon Sep 20 15:54:33 UTC 2010 x86_64 x86_64 x86_64 GNU/Linux
  eth0      Link encap:Ethernet  HWaddr 40:40:B1:7A:52:7E
            inet addr:50.57.117.249  Bcast:50.57.117.255  Mask:255.255.255.0
            inet6 addr: fe80::4240:b1ff:fe7a:527e/64 Scope:Link
            UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
            RX packets:54 errors:0 dropped:0 overruns:0 frame:0
            TX packets:62 errors:0 dropped:0 overruns:0 carrier:0
            collisions:0 txqueuelen:1000
            RX bytes:5880 (5.7 KiB)  TX bytes:6331 (6.1 KiB)
            Interrupt:24

  eth1      Link encap:Ethernet  HWaddr 40:40:8E:4B:52:23
            inet addr:10.182.131.159  Bcast:10.182.159.255  Mask:255.255.224.0
            inet6 addr: fe80::4240:8eff:fe4b:5223/64 Scope:Link
            UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
            RX packets:3 errors:0 dropped:0 overruns:0 frame:0
            TX packets:12 errors:0 dropped:0 overruns:0 carrier:0
            collisions:0 txqueuelen:1000
            RX bytes:188 (188.0 b)  TX bytes:720 (720.0 b)
            Interrupt:25

  lo        Link encap:Local Loopback
            inet addr:127.0.0.1  Mask:255.0.0.0
            inet6 addr: ::1/128 Scope:Host
            UP LOOPBACK RUNNING  MTU:16436  Metric:1
            RX packets:0 errors:0 dropped:0 overruns:0 frame:0
            TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
            collisions:0 txqueuelen:0
            RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)

  /root</output>
</instance>

Create a new instance

To create a new instance use call POST /api/instances. At least, clients must specify the image from which the virtual machine instance is created. Optionally, a client may also specify a hardware profile and a realm (with default values used otherwise). Clients can also provide a name for the new instance though this is not supported by all back-end cloud providers. You can check whether a given feature is available in the response to the Deltacloud server API entry point. The details of the new instance are returned in response to this operation.

To create an instance in the Amazon EC2 cloud a client can also specify the name of the used EC2 keypair as well as the firewalls (EC2 security groups) that the instance should be launched into. The EC2 keypair is specified with the parameter keyname while firewalls are specified sequentially as firewalls1 ... firewalls2 ... etc.

See the example below. The values for public and private addresses are blank in the server response, because they have not yet been assigned by the cloud provider. Subsequent requests for the instance details will provide these values.

As with other POST operations in the Deltacloud API, clients may specify parameters as multipart/form-data or as x-www-url-form-urlencoded content type, as you can see in examples below.

Client request (AWS EC2):

POST /api/instances?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
Content-Length: 107
Content-Type: application/x-www-form-urlencoded

keyname=eftah&image_id=ami-f51aff9c&realm_id=us-east-1c&hwp_id=c1.medium&
firewalls1=default&firewalls2=test

Server response:

HTTP/1.1 201 Created
Content-Type: application/xml
Content-Length: 1183

<?xml version='1.0' encoding='utf-8' ?>
<instance href='http://localhost:3001/api/instances/i-cbb861aa' id='i-cbb861aa'>
  <name>ami-f51aff9c</name>
  <owner_id>393485797142</owner_id>
  <image href='http://localhost:3001/api/images/ami-f51aff9c' id='ami-f51aff9c'></image>
  <realm href='http://localhost:3001/api/realms/us-east-1c' id='us-east-1c'></realm>
  <state>PENDING</state>
  <hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.medium' id='c1.medium'>
  </hardware_profile>
  <actions>
    <link href='http://localhost:3001/api/instances/i-cbb861aa/stop' method='post' rel='stop' />
    <link href='http://localhost:3001/api/instances/i-cbb861aa/run;id=i-cbb861aa' method='post' rel='run' />
  </actions>
  <launch_time>2011-07-22T16:09:45.000Z</launch_time>
  <public_addresses></public_addresses>
  <private_addresses></private_addresses>
  <firewalls>
    <firewall href='http://localhost:3001/api/firewalls/test' id='test'></firewall>
    <firewall href='http://localhost:3001/api/firewalls/default' id='default'></firewall>
  </firewalls>
  <authentication type='key'>
    <login>
      <keyname>eftah</keyname>
    </login>
  </authentication>
</instance>

In the following example you can see that the client provides the optional name parameter and that the created instance uses password type of authentication. Furthermore, the client uses a content-type of application/x-www-form-urlencoded. The username and password are returned with the details of the new instance:

Example request: (Rackspace Cloudservers)

POST /api/instances?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
Content-Length: 34
Content-Type: application/x-www-form-urlencoded

image_id=53&hwp_id=1&name=myserver

Server response:

HTTP/1.1 201 Created
Content-Type: application/xml
Content-Length: 883

<?xml version='1.0' encoding='utf-8' ?>
<instance href='http://localhost:3002/api/instances/20112212' id='20112212'>
  <name>myserver</name>
  <owner_id>mandreou</owner_id>
  <image href='http://localhost:3002/api/images/53' id='53'></image>
  <realm href='http://localhost:3002/api/realms/us' id='us'></realm>
  <state>PENDING</state>
  <hardware_profile href='http://localhost:3002/api/hardware_profiles/1' id='1'>
  </hardware_profile>
  <actions>
    <link href='http://localhost:3002/api/instances/20112212/run;id=20112212' method='post' rel='run' />
  </actions>
  <public_addresses><address>50.57.116.72</address></public_addresses>
  <private_addresses><address>10.182.143.64</address></private_addresses>
  <authentication type='password'>
    <login>
      <username>root</username>
      <password>myserver4OvKh7Ak3</password>
    </login>
  </authentication>
</instance>
×

Note:

The Deltacloud does not report potential errors, if you are creating an instance in vSphere. When you launch an instance, Deltacloud does not wait until the task is finished. Instead of that, Deltacloud creates a YAML representation of the instance in vSphere datastore. The YAML instance is in a 'PENDING' state until the 'real' instance is created. If the real instance fails to create, the YAML representation is removed. However, Deltacloud does not send you any error message.

Keys