| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <title>Images</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="images">Images</h3> |
| |
| <p> |
| Images are used to launch instances. Each image represents a virtual machine image in the back-end cloud, containing the root partition and initial storage for an instance operating system. An image has these attributes: |
| </p> |
| |
| <ul> |
| <li>a human-readable <strong>name</strong> |
| </li> |
| <li>a <strong>description</strong> |
| </li> |
| <li>an <strong>owner_id</strong> |
| </li> |
| <li>an <strong>architecture</strong> |
| </li> |
| <li>a <strong>state</strong> |
| </li> |
| </ul> |
| |
| <p> |
| The <strong>owner_id</strong> identifies the user account to which the image belongs. The <strong>architecture</strong> attribute refers to whether the image will create an instance with 32 or 64-bit processor. The values that the Deltacloud server returns for this attribute are thus i386 and x86_64 respectively. The state attribute varies between back-end clouds (it depends on a cloud provider). For example, AWS EC2 image state can be one of AVAILABLE, PENDING or FAILED, whereas Rackspace Cloudservers image state can be one of UNKNOWN, PREPARING, ACTIVE, QUEUED or FAILED. Finally, each image also contains an <code><actions></code> attribute which specifies the URI to which a client may issue a <strong>HTTP POST</strong> for creation of an instance from the given image. |
| </p> |
| |
| </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">Realms</a></li> |
| <li><a href="hardware-profiles.html">Hardware profiles</a></li> |
| <li class="active"><a href="#images">Images</a></li> |
| <li><a href="instance-states.html">Instance states</a></li> |
| <li><a href="instances.html">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> |
| |
| <p><br></p> |
| |
| <ul class="nav nav-pills"> |
| <li class="active"><a href="#tab1" data-toggle="tab">Get a list of all images</a></li> |
| <li><a href="#tab2" data-toggle="tab">Get the details of an image</a></li> |
| <li><a href="#tab3" data-toggle="tab">Create/delete an image</a></li> |
| </ul> |
| |
| <hr> |
| |
| <div class="tab-content"> |
| <div class="tab-pane active" id="tab1"> |
| |
| <h4>Get the list of all images</h4> |
| |
| <p> |
| To return a list of all images available in the back-end cloud use call <strong>GET /api/images</strong>. By default this call will return all images that are available to the given user account. Optionally a client may restrict the list of images returned by specifying the <strong>owner_id</strong> or <strong>architecture</strong> parameters in the request (architecture is one of x86_64 for 64-bit processors or i386 for 32-bit processors). The example below restricts the image list to 64-bit architecture images belonging to owner_id 023801271342. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| GET /api/images?owner_id=023801271342&architecture=x86_64&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: 1971 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <images> |
| <image href='http://localhost:3001/api/images/ami-eea35787' id='ami-eea35787'> |
| <name>sles-10-sp3-v1.00.x86_64</name> |
| <owner_id>013907871322</owner_id> |
| <description>SUSE Linux Enterprise Server 10 Service Pack 3 for x86_64 (v1.00)</description> |
| <architecture>x86_64</architecture> |
| <state></state> |
| <actions> |
| <link href='http://localhost:3001/api/instances;image_id=ami-eea35787' method='post' rel='create_instance' /> |
| </actions> |
| </image> |
| <image href='http://localhost:3001/api/images/ami-6e649707' id='ami-6e649707'> |
| <name>sles-11-sp1-hvm-v1.00.x86_64</name> |
| <owner_id>013907871322</owner_id> |
| <description>SUSE Linux Enterprise Server 11 Service Pack 1 for HVM x86_64 (v1.00)</description> |
| <architecture>x86_64</architecture> |
| <state></state> |
| <actions> |
| <link href='http://localhost:3001/api/instances;image_id=ami-6e649707' method='post' rel='create_instance' /> |
| </actions> |
| </image> |
| <image href='http://localhost:3001/api/images/ami-e4a7558d' id='ami-e4a7558d'> |
| <name>sles-11-sp1-hvm-v1.01.x86_64</name> |
| <owner_id>013907871322</owner_id> |
| <description>SUSE Linux Enterprise Server 11 Service Pack 1 for HVM x86_64 (v1.01)</description> |
| <architecture>x86_64</architecture> |
| <state></state> |
| <actions> |
| <link href='http://localhost:3001/api/instances;image_id=ami-e4a7558d' method='post' rel='create_instance' /> |
| </actions> |
| </image> |
| <image href='http://localhost:3001/api/images/ami-e4a3578d' id='ami-e4a3578d'> |
| <name>sles-11-sp1-v1.00.x86_64</name> |
| <owner_id>013907871322</owner_id> |
| <description>SUSE Linux Enterprise Server 11 Service Pack 1 for x86_64 (v1.00)</description> |
| <architecture>x86_64</architecture> |
| <state></state> |
| <actions> |
| <link href='http://localhost:3001/api/instances;image_id=ami-e4a3578d' method='post' rel='create_instance' /> |
| </actions> |
| </image> |
| </images> |
| </pre> |
| |
| </div> |
| <div class="tab-pane" id="tab2"> |
| |
| <h4>Get details of an image</h4> |
| |
| <p>To retrieve the description of a specific image use call <strong>GET /api/images/:id</strong>.</p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| GET /api/images/14?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: 433 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <image href='http://localhost:3002/api/images/14' id='14'> |
| <name>Red Hat Enterprise Linux 5.4</name> |
| <owner_id>jsmith</owner_id> |
| <description>Red Hat Enterprise Linux 5.4</description> |
| <architecture>x86_64</architecture> |
| <state>ACTIVE</state> |
| <actions> |
| <link href='http://localhost:3002/api/instances;image_id=14' method='post' rel='create_instance' /> |
| </actions> |
| </image> |
| </pre> |
| |
| </div> |
| <div class="tab-pane" id="tab3"> |
| |
| <h4>Create an image</h4> |
| |
| <p> |
| To create a new image from an existing running instance use call <strong>POST /api/images</strong>. This operation is not available to all cloud providers and for some cloud providers this operation is not possible for all instances. For example, in the Amazon EC2 cloud, you can create a custom image from EBS backed instances but not from root-store instances. |
| </p> |
| |
| <div class="alert alert-error"> |
| <a class="close" data-dismiss="alert" href="#">×</a> |
| <strong>Note: </strong> |
| <p> |
| RHVE-M, vSphere and Fujitsu GCP providers allow you to create an image only from a stopped instance, not from a running instance. |
| </p> |
| </div> |
| |
| <p> |
| The Deltacloud API provides a mechanism with which clients can determine whether a given instance may be saved as a custom image. If an instance snapshot is possible, the instance XML <code><actions></code> list contains a <strong>create_image</strong> action. This action defines the client's URI which is used in creating the new image. For example: |
| </p> |
| |
| <pre> |
| ... |
| <actions> |
| <link href='http://localhost:3002/api/instances/20109341/reboot' method='post' rel='reboot' /> |
| <link href='http://localhost:3002/api/instances/20109341/stop' method='post' rel='stop' /> |
| <link href='http://localhost:3002/api/instances/20109341/run;id=20109341' method='post' rel='run' /> |
| <link href='http://localhost:3002/api/images;instance_id=20109341' method='post' rel='create_image' /> |
| </actions> |
| ... |
| </pre> |
| |
| <p> |
| To create a new image the client must specify the <strong>instance_id</strong> of the running instance. Optionally, the client may also provide a <strong>name</strong> and a <strong>description</strong>. The parameters may be defined as multipart/form-data fields in the client POST. |
| </p> |
| |
| <p> |
| Alternatively, clients may also specify parameters using a content-type of application/x-www-form-urlencoded. The Deltacloud server will respond to a successful operation with <strong>HTTP 201 Created</strong> and provide details of the newly created image. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| POST /api/images?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3002 |
| Accept: */* |
| Content-Length: 96 |
| Content-Type: application/x-www-form-urlencoded |
| |
| instance_id=20109341&name=customisedserver&description=jsmith%20cu |
| stomised%20web%20server%20July%2021%202011 |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 201 Created |
| Content-Type: application/xml |
| Content-Length: 427 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <image href='http://localhost:3002/api/images/12346145' id='12346145'> |
| <name>customisedserver</name> |
| <owner_id>mandreou</owner_id> |
| <description>customisedserver</description> |
| <architecture>x86_64</architecture> |
| <state>QUEUED</state> |
| <actions> |
| <link href='http://localhost:3002/api/instances;image_id=12346145' method='post' rel='create_instance' /> |
| </actions> |
| </image> |
| </pre> |
| |
| <div class="alert alert-error"> |
| <a class="close" data-dismiss="alert" href="#">×</a> |
| <strong>Note: </strong> |
| <p>When you create an image from a stopped instance in <strong>vSphere</strong> cloud, this particular instance is marked as <strong>template</strong> and it is also removed from Instances.</p> |
| |
| <p>Unlike other providers, vSphere does not support assigning a <strong>name</strong> and a <strong>description</strong> to the image when you create an image from a stopped instance. The image created in vSphere ignores these attributes passed to the API during the creation.</p> |
| <p><strong>Fujitsu GCP</strong> does not return an ID that can be used to track the state of the image |
| creation. Poll the list of all images until your image appears. This will contain the |
| proper image id that can be used in other image actions. |
| </p> |
| |
| </div> |
| |
| <h4>Delete an image</h4> |
| |
| <p> |
| To delete the specified image from the back-end cloud use call <strong>DELETE /api/images/:id</strong>. The Deltacloud server will return a <strong>HTTP 204 No Content</strong> after a succesful operation: |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| DELETE /api/images/12346145?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 204 No Content |
| </pre> |
| |
| </div> |
| </div> |
| |
| <p><a class="btn btn-inverse btn-large" style="float: right" href="instance-states.html">Instance states <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'> </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> |
