--- site_name: Deltacloud API title: Images ---

Images

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:

The owner_id identifies the user account to which the image belongs. The architecture 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 <actions> attribute which specifies the URI to which a client may issue a HTTP POST for creation of an instance from the given image.


Get the list of all images

To return a list of all images available in the back-end cloud use call GET /api/images. 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 owner_id or architecture 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.

Example request:

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

Server response:

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>

Get details of an image

To retrieve the description of a specific image use call GET /api/images/:id.

Example request:

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

Server response:

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>

Create an image

To create a new image from an existing running instance use call POST /api/images. 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.

× Note:

RHVE-M and vSphere provid

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 <actions> list contains a create_image action. This action defines the client's URI which is used in creating the new image. For example: 

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

To create a new image the client must specify the instance_id of the running instance. Optionally, the client may also provide a name and a description. The parameters may be defined as multipart/form-data fields in the client POST.

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 HTTP 201 Created and provide details of the newly created image.

Example request:

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

Server response:

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>
× Note:

When you create an image from a stopped instance in vSphere driver, this particular instance is marked as template and it is also removed from Instances.

Unlike other providers, vSphere does not support assigning a name and a description 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.

Delete an image

To delete the specified image from the back-end cloud use call DELETE /api/images/:id. The Deltacloud server will return a HTTP 204 No Content after a succesful operation:

Example request:

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

Server response:

HTTP/1.1 204 No Content
Instance states