<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Instances</title>
    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
    <!--[if lt IE 9]>
    <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->

    <!-- Le JavaScript -->
    <script src="/assets/js/jquery-1.7.1.min.js" type="text/javascript"></script>
    <script src="/assets/js/bootstrap-dropdown.js" type="text/javascript"></script>
    <script src="/assets/js/jquery.tweet.js" type="text/javascript"></script>
    <script src="/assets/js/application.js" type="text/javascript"></script>
    <script src="/assets/js/bootstrap-transition.js"></script>
    <script src="/assets/js/bootstrap-alert.js"></script>
    <script src="/assets/js/bootstrap-modal.js"></script>
    <script src="/assets/js/bootstrap-scrollspy.js"></script>
    <script src="/assets/js/bootstrap-tab.js"></script>
    <script src="/assets/js/bootstrap-tooltip.js"></script>
    <script src="/assets/js/bootstrap-popover.js"></script>
    <script src="/assets/js/bootstrap-button.js"></script>
    <script src="/assets/js/bootstrap-collapse.js"></script>
    <script src="/assets/js/bootstrap-carousel.js"></script>
    <script src="/assets/js/bootstrap-typeahead.js"></script>

    <!-- Le styles -->
    <link href="/assets/css/bootstrap.css" rel="stylesheet">
    <link href="/assets/css/application.css" rel="stylesheet">
    <link rel="shortcut icon" href="/assets/img/favicon.ico">
  </head>

  <body><div style="background: red"><h1>2015/07/20 - Apache Deltacloud has been retired. </h1><h2>For more information, please explore the <a href="http://attic.apache.org/">Attic</a>. </h2></div>

    <div class="navbar navbar-fixed-top">
      <div class="navbar-inner">
        <div class="container">
          <a class="brand" href="/"><img src="/assets/img/logo.png" width="152"
            alt="Deltacloud API"/></a>
          <ul class="nav top-nav">
  <li><a href="/">Home</a></li>
  <li class="dropdown">
    <a href="#" class="dropdown-toggle" data-toggle="dropdown">About<b class="caret"></b></a>
    <ul class="dropdown-menu">
      <li><a href="/about.html">What is Deltacloud?</a></li>
      <li><a href="/drivers.html#drivers">Supported Providers</a></li>
    </ul>
  </li>
  <li><a href="/download.html">Download</a></li>
  <li class="dropdown">
    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Installation<b class="caret"></b></a>
    <ul class="dropdown-menu">
      <li><a href="/install-deltacloud.html">Install Deltacloud</a></li>
      <li><a href="/run-deltacloud-server.html">Run the Deltacloud Server</a></li>
    </ul>
  </li>
  <li class="dropdown">
    <a href="/usage.html" class="dropdown-toggle" data-toggle="dropdown">Usage<b class="caret"></b></a>
    <ul class="dropdown-menu">
      <li><a href="/usage.html#usingapi">Using API</a></li>
      <li><a href="/usage.html#clients">Client Libraries</a></li>
      <li><a href="/command-tools.html">Command Line Tools</a></li>
    </ul>
  </li>
  <li class="dropdown">
    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contribute<b class="caret"></b></a>
    <ul class="dropdown-menu">
      <li><a href="/getting-sources.html">Getting Sources</a></li>
      <li><a href="/how-to-contribute.html">How Can I Contribute?</a></li>
    </ul>
  </li>
  <li class="dropdown">
    <a href="#" class="dropdown-toggle" data-toggle="dropdown">API<b class="caret"></b></a>
    <ul class="dropdown-menu">
      <li><a href="/rest-api.html">Deltacloud REST API</a></li>
      <li><a href="/curl-examples.html">Deltacloud API cURL examples</a></li>
      <li><a href="/drivers.html">Drivers API</a></li>
    </ul>
  </li>
  <li class="dropdown">
    <a href="#" class="dropdown-toggle" data-toggle="dropdown">CIMI<b class="caret"></b></a>
    <ul class="dropdown-menu">
      <li><a href="/cimi-rest.html">CIMI REST API</a></li>
      <li><a href="/cimi-curl.html">CIMI cURL Examples</a></li>
    </ul>
  </li>
  <li><a href="/contact.html">Contact</a></li>
</ul>

        </div>
      </div>

    </div>

    <div class="container content">

      <p><br></p>

<div class="row">
  <div class="span9">

<h3 id="instances">Instances</h3>

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

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

  </div>
  <div class="span3">
  
<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>
  <ul class="nav nav-list">
    <li><a href="compute-resources.html">Realms</a></li>
    <li><a href="hardware-profiles.html">Hardware profiles</a></li>
    <li><a href="images.html">Images</a></li>
    <li><a href="instance-states.html">Instance states</a></li>
    <li class="active"><a href="#instances">Instances</a></li>
    <li><a href="keys.html">Keys</a></li>
    <li><a href="firewalls.html">Firewalls</a></li>
    <li><a href="addresses.html">Addresses</a></li>
    <li><a href="load-balancers.html">Load balancers</a></li>
  </ul>
  <li><a href="storage-resources.html">Storage resources</a></li>
</ul>

  </div>
</div>

<ul class="nav nav-pills">
  <li id="instance1" class="active"><a href="#tab1" data-toggle="tab">Get a list of all instances</a></li>
  <li id="instance2"><a href="#tab2" data-toggle="tab">Get the details of an instance</a></li>
  <li id="instance3"><a href="#tab3" data-toggle="tab">Launch an action</a></li>
  <li id="instance4"><a href="#tab4" data-toggle="tab">Create an instance</a></li>
</ul>

<hr>

<div class="tab-content">
  <div class="tab-pane active" id="tab1">

  <h4 id="list">Get a list of all current instances</h4>

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

  <p>
  Example request:
  </p>

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

  <p>Client response:</p>

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

  </div>
  <div class="tab-pane" id="tab2">

  <h4 id="get-instance">Get the details of an instance</h4>

  <p>
  To get the details of a specific instance use call <strong>GET /api/instances/:id</strong>. The example below shows an instance launched in the Rackspace Cloudservers cloud. As you can see, the type of authentication is <strong>password</strong> 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 <strong><em>Create an instance</em></strong> section.
  </p>

  <p>Example request:</p>

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

  <p>Server response:</p>

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

  </div>
  <div class="tab-pane" id="tab3">

  <h4 id="actions">Launch an action on an instance</h4>

  <p>
  To launch an action on an instance use call <strong>POST /api/instances/:id/:action</strong>. 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 <code>&lt;actions&gt;</code> attribute in the Deltacloud server response to the <strong>GET /api/instances/:id</strong> call (<strong><em>Get the details of an instance</em></strong> section). The first example below shows a <strong>reboot</strong> action on a currently running instance, followed by a <strong>stop</strong> action.
  </p>

  <p>
  After invoking the stop operation, the instance state may still be reported as <strong>RUNNING</strong> 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.
  </p>

  <p>
  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 <strong>SSH</strong>. The Deltacloud server will return the output of that command to the client. This is reported as the <strong>run</strong> action in the list of instance actions, if it is available. The <strong>cmd</strong> parameter specifies the command, which is executed on a running instance.The <strong>private_key</strong> parameter specifies the authentication for cloud providers that expect key based authentication for connecting to instances . For those cloud providers that use <strong>username/password</strong> for authentication, the <strong>password</strong> 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).
  </p>

  <p>Example request (<strong>reboot</strong>):</p>

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

  <p>Server response:</p>

<pre>
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1322

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

  <p>Example request (<strong>stop</strong>):</p>

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

  <p>Server response:</p>

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

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

  <p>
  Example request (<strong>run-on-instance Amazon EC2</strong>): 
  </p>

<div class="alert alert-error">
  <a class="close" data-dismiss="alert" href="#">×</a>
  <strong>Note:</strong> 
  <p>
  Run-on-instance requests to EC2 instances will fail with <strong>502 Bad Gateway - Execution Expired</strong> 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 <a href="firewalls.html">firewalls</a> collection.</p>
</div>

<pre>
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--
</pre>

  <p>Server response:</p>

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

&lt;instance href='http://localhost:3001/api/instances/i-afde73ce' id='i-afde73ce'&gt;
  &lt;public_address&gt;
    ec2-50-19-59-126.compute-1.amazonaws.com
  &lt;/public_address&gt;
  &lt;command&gt;
    uname -a; ls -l
  &lt;/command&gt;
  &lt;output&gt;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
  &lt;/output&gt;
&lt;/instance&gt;
</pre>

  <p>Example request (<strong>run-on-instance Rackspace Cloudservers</strong>):</p>

<pre>
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--
</pre>

  <p>Server response:</p>

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

&lt;instance href='http://localhost:3002/api/instances/20117112' id='20117112'&gt;
  &lt;public_address&gt;
    50.57.117.249
  &lt;/public_address&gt;
  &lt;command&gt;
    uname -a; ifconfig; pwd
  &lt;/command&gt;
  &lt;output&gt;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&lt;/output&gt;
&lt;/instance&gt;
</pre>

  </div>
  <div class="tab-pane" id="tab4">

  <h4 id="post">Create a new instance</h4>

  <p>
  To create a new instance use call <strong>POST /api/instances</strong>. 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.
  </p>

  <p>
  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. 
  </p>

  <p>
  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.
  </p>

  <p>
  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.
  </p>

  <p>Client request (<strong>AWS EC2</strong>):</p>

<pre>
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&amp;image_id=ami-f51aff9c&amp;realm_id=us-east-1c&amp;hwp_id=c1.medium&amp;
firewalls1=default&amp;firewalls2=test
</pre>

  <p>Server response:</p>

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

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

  <p>
  In the following example you can see that the client provides the optional name parameter and that the created instance uses <strong>password</strong> 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:
  </p>

  <p>Example request: (<strong>Rackspace Cloudservers</strong>)</p>

<pre>
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&amp;hwp_id=1&amp;name=myserver
</pre>

  <p>Server response:</p>

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

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

<div class="alert alert-error">
  <a class="close" data-dismiss="alert" href="#">×</a>
  <h4 class="alert-heading">Note:</h4>
  <p>
  The Deltacloud does not report potential errors, if you are creating an instance in <strong>vSphere</strong>. 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.
  </p>
</div>

  </div>
</div>

<p><a class="btn btn-inverse btn-large" style="float: right" href="keys.html">Keys <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a></p>

<p><br></p>


      <footer class="footer">
        <p class="pull-right"><span class='icon-circle-arrow-up'>&nbsp;</span><a href="#">Back to top</a></p>
        <div class='row'>
          <div class='span3'>
            <img src="/assets/img/asf.png" alt="Apache Software Foundation"/>
          </div>
          <div class='span9'>
            <strong>Apache Deltacloud</strong> is a top-level project at the <a
              href="http://www.apache.org">Apache Software Foundation</a>,
            having graduated from the ASF Incubator in October
            2011. Through a collaborative and meritocratic development process, Apache
            projects deliver enterprise-grade, freely available software products that
            attract large communities of users. 
          </div>
        </div>
      </footer>

    </div> <!-- /container -->

<!-- Piwik -->
<script type="text/javascript">
var pkBaseURL = (("https:" == document.location.protocol) ? "https://stats.salasaga.org/aeolus/piwik/" : "http://stats.salasaga.org/aeolus/piwik/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
try {
var piwikTracker = Piwik.getTracker(pkBaseURL + "piwik.php", 2);
piwikTracker.trackPageView();
piwikTracker.enableLinkTracking();
} catch( err ) {}
</script><noscript><p><img src="http://stats.salasaga.org/aeolus/piwik/piwik.php?idsite=2" style="border:0" alt="" /></p></noscript>
<!-- End Piwik Tracking Code -->

  </body>
</html>