Working with oVirt via EC2/CIMI APIs using Deltacloud

Overview

The oVirt engine is a large scale, centralized  virtualization management platform, which provides many Infrastructure as a Service (IaaS) capabilities. Every such capability is exposed via rich API, UI, CLI and SDK.

Motivation

More and more cloud providers start to support more standard and common APIs, such as EC2 and CIMI API. It is useful when working in heterogeneous virtualization environment, in which you have more than one cloud provider, or even when you already have scripts developed to use these APIs, and you would like to use them on top of a different cloud provider. Moreover, existing projects such as Aeolus, HEAT, Synaps and more, support (or plan to support) working with common API(s).

The Deltacloud project allows you to use oVirt (and other cloud providers) using a standard and common cloud APIs, that include EC2, CIMI and the Deltacloud API. This post will focus on EC2 and CIMI APIs, which are new additions to the Deltacloud server.

This blog post will show how you can use Deltacloud in order to perform basic operations via EC2/CIMI APIs, on top of the oVirt engine. This post is informative and technical, and it is directed for those who are interested in a solution for using oVirt via common cloud APIs.

Note that the examples in this blog post were run on oVirt engine 3.1and Deltacloud server version 1.0.4, both running on Fedora 17.

Installing and Running the Deltacloud server

 

Installing the Deltacloud server

The deltacloud server can be installed very easily, using the following commands (Useful for Deltacloud development environment):

yum install rubygems gcc-c++ libxml libxslt libxslt-devel gem install rake deltacloud-core

Or just using the following command (In a Deltacloud deployment environment):
yum install deltacloud-core-all

Running the Deltacloud server

In order to run the Deltacloud server, on top of oVirt, exposing all three APIs (EC2, CIMI and the Deltacloud API) use the following command:

deltacloudd -i rhevm -f cimi,ec2,deltacloud (use the -r HOSTNAME option to set an address to bind, default is localhost)

Note that in this command we haven't set the details of the oVirt engine URL. You can do that by setting the API_PROVIDER environment variable. Each Deltacloud server request is in a specific oVirt Data-Center scope, so this variable must contain both the oVirt engine URL, and the oVirt Data-Center ID.

In order to get the available oVirt Data-Centers you can use the oVirt CLI, using the following commands:

$ ovirt-shell -l http://<engine server>:<engine port> -u <user> -p <password> [oVirt shell]# list datacenters id : 79221158-0d50-11e2-a8af-17acc9433061 name : Default description: The default Data Center


Now, you can set the API_PROVIDER as follows:

API_PROVIDER="http://localhost:8080/api;79221158-0d50-11e2-a8af-17acc9433061"

And run the Deltacloud server as shown before.

Setting the API_PROVIDER only sets the default engine and Data-Center. If you want a specific request to use a different oVirt engine, or a different Data-Center, you can set the "X-Deltacloud-Provider" HTTP Header parameter in your request to a different oVirt engine+Data-Center, and the request scope will change accordingly.

Note that in Fedora, if you installed the deltacloud-core-all package, then you'll get a deltacloud service, that reads its configuration from /etc/sysconfig/deltacloud-core. The problem is, that you cannot configure there the APIs you would like deltacloud to expose, so for now the manual approach is the only way (unless you change the startup scripts to do that for you).

Examples

Now lets move to some examples on using EC2 and CIMI on top of oVirt

EC2 Examples

Note that some operations support passing more than one object to do the operation on, for example InstanceId.1=...&InstanceId.2=... and etc. Deltacloud currently doesn't support more than one object, so all examples contain only one such object.

Get oVirt Clusters (Get Availability Zones)

Request

HTTP GET http://localhost:3001/ec2/?Action=DescribeAvailabilityZones

Response

<DescribeAvailabilityZonesResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'> <requestId>7c14876387aa8d47b2ff1b1edf0d253f</requestId> <availabilityZoneInfo> <item> <zoneName>99408929-82cf-4dc7-a532-9d998063fa95</zoneName> <zoneState>AVAILABLE</zoneState> <regionName>Default</regionName> </item> <item> <zoneName>77d52ef6-11e3-11e2-be8c-87a6485627fe</zoneName> <zoneState>AVAILABLE</zoneState> <regionName>my_cluster</regionName> </item> </availabilityZoneInfo> </DescribeAvailabilityZonesResponse>

Get oVirt Templates (Get AMIs)

Request

HTTP GET http://localhost:3001/ec2/?Action=DescribeImages

Response

<DescribeImagesResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'> <requestId>a9f98b46f42bd96da30fe5b095617e0d</requestId> <imagesSet> <item> <imageId>00000000-0000-0000-0000-000000000000</imageId> <imageState>ok</imageState> <imageOwnerId>admin@internal</imageOwnerId> <architecture>x86_64</architecture> <imageType>machine</imageType> <name>Blank</name> <description>Blank template</description> </item> <item> <imageId>77ea7521-3017-4ee9-bcdf-d566178991c6</imageId> <imageState>ok</imageState> <imageOwnerId>admin@internal</imageOwnerId> <architecture>x86_64</architecture> <imageType>machine</imageType> <name>server_template</name> <description>Template for servers</description> </item> </imagesSet> </DescribeImagesResponse>

Create VM from Template in a Cluster (Run Instance created from AMI in an Availability Zone)

Request

HTTP GET http://localhost:3001/ec2/?Action=RunInstances&Placement.AvailabilityZone=77d52ef6-11e3-11e2-be8c-87a6485627fe&ImageId=77ea7521-3017-4ee9-bcdf-d566178991c6

Response

<RunInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'> <requestId>daad0aaa272ee19e2c8645e77b620e38</requestId> <reservationId>r-11111111</reservationId> <ownerId>deltacloud</ownerId> <groupSet> <item> <groupId>sg-11111111</groupId> <groupName>default</groupName> </item> </groupSet> <instanceSet> <item> <instanceId>84623036-49fe-4f22-ac6f-ff526e8b82be</instanceId> <imageId>77ea7521-3017-4ee9-bcdf-d566178991c6</imageId> <instanceType>SERVER</instanceType> <launchTime>2012-10-10T09:53:08.984+02:00</launchTime> <ipAddress>192.168.1.27</ipAddress> <dnsName>192.168.1.27</dnsName> <architecture>i386</architecture> <instanceState> <code>0</code> <name>pending</name> </instanceState> <placement> <availabilityZone>77d52ef6-11e3-11e2-be8c-87a6485627fe</availabilityZone> <groupName></groupName> <tenancy>default</tenancy> </placement> </item> </instanceSet> </RunInstancesResponse>

Notes:

• IP Address will be accurate only if guest agent is installed
• InstanceType is hardcoded as SERVER, as oVirt still doesn't have hardware configuration object (oVirt template contains both hardware and software configuration). Adding instance types is planned for oVirt 3.2.
• Passing User-Data is supported, currently via oVirt hook that is installed on the oVirt host, but in the future the native VM payload will be supported by Deltacloud as well.

Get VM(s) (Describe Instances)

Request

HTTP GET All instances - http://localhost:3001/ec2/?Action=DescribeInstances Specific instance - http://localhost:3001/ec2/?Action=DescribeInstances&InstanceId.1=84623036-49fe-4f22-ac6f-ff526e8b82be”

Response

<DescribeInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'> <instanceSet> <item> <instanceId>84623036-49fe-4f22-ac6f-ff526e8b82be</instanceId> <imageId>77ea7521-3017-4ee9-bcdf-d566178991c6</imageId> <instanceType>SERVER</instanceType> <launchTime>2012-10-10T09:53:08.984+02:00</launchTime> <ipAddress>192.168.1.27</ipAddress> <dnsName>192.168.1.27</dnsName> <architecture>i386</architecture> <instanceState> <code>80</code> <name>stopped</name> </instanceState> <placement> <availabilityZone>77d52ef6-11e3-11e2-be8c-87a6485627fe</availabilityZone> <groupName></groupName> <tenancy>default</tenancy> </placement> </item> </instanceSet> </DescribeInstancesResponse>

Start VM (Start Instances)

Request

HTTP GET http://localhost:3001/ec2/?Action=StartInstances&InstanceId.1=84623036-49fe-4f22-ac6f-ff526e8b82be”

Response

<StartInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'> <requestId>0abf89a0b59c9f090818872f574766e5</requestId> <instancesSet> <item> <instanceId>84623036-49fe-4f22-ac6f-ff526e8b82be</instanceId> <currentState> <code>0</code> <name>pending</name> </currentState> <previousState> <code>-1</code> <name>unknown</name> </previousState> </item> </instancesSet> </StartInstancesResponse>

Note that Deltacloud doesn't query for the status of the object before running this action, so it is set to unknown (-1).

Stop VM (Stop Instances)

Request

HTTP GET http://localhost:3001/ec2/?Action=StopInstances&InstanceId.1=84623036-49fe-4f22-ac6f-ff526e8b82be”

Response

<StopInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'> <requestId>49969b2552340028a4bda5a09e536778</requestId> <instancesSet> <item> <instanceId>84623036-49fe-4f22-ac6f-ff526e8b82be</instanceId> <currentState> <code>64</code> <name>stopping</name> </currentState> <previousState> <code>-1</code> <name>unknown</name> </previousState> </item> </instancesSet> </StopInstancesResponse>

Note that Deltacloud doesn't query for the status of the object before running this action, so it is set to unknown (-1).

Delete VM (Terminate Instances)

Request

HTTP GET http://localhost:3001/ec2/?Action=TerminateInstances&InstanceId.1=84623036-49fe-4f22-ac6f-ff526e8b82be”

Response

<TerminateInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'> <requestId>67392f70be9b6759ba830b85153661f5</requestId> <instancesSet> <item> <instanceId>5ee314f5-a01b-41f3-81f7-fe4acb6c31f9</instanceId> <currentState> <code>32</code> <name>shutting-down</name> </currentState> <previousState> <code>-1</code> <name>unknown</name> </previousState> </item> </instancesSet> </TerminateInstancesResponse>

Note that Deltacloud doesn't query for the status of the object before running this action, so it is set to unknown (-1).

CIMI Examples

The CIMI API is a REST-based API, supporting GET (retrieve objects/collections), POST (create new objects), and DELETE (delete objects). PUT (modifying objects) is currently not supported in Deltacloud.

Get oVirt Templates (Get Images)

Request
In the request we use the URI of the machine_images collection.
HTTP GET http://localhost:3001/cimi/machine_images

Response
The response is a collection of Machine Images. Note that according to the CIMI spec, the ID is the resource URI, the name is the GUID, and the description is the name.
<Collection xmlns="http://schemas.dmtf.org/cimi/1"> <id>http://localhost:3001/cimi/machine_images</id> <name>default</name> <description>MachineImage Collection for the Rhevm driver</description> <count>3</count> <MachineImage> <id>http://localhost:3001/cimi/machine_images/00000000-0000-0000-0000-000000000000</id> <name>00000000-0000-0000-0000-000000000000</name> <description>Blank template</description> <created>2012-10-11 11:20:26 +0200</created> <imageLocation href="rhevm://00000000-0000-0000-0000-000000000000" /> </MachineImage> <MachineImage> <id>http://localhost:3001/cimi/machine_images/77ea7521-3017-4ee9-bcdf-d566178991c6</id> <name>77ea7521-3017-4ee9-bcdf-d566178991c6</name> <description>Server template</description> <created>2012-10-11 11:20:26 +0200</created> <imageLocation href="rhevm://77ea7521-3017-4ee9-bcdf-d566178991c6" /> </MachineImage> <MachineImage> <id>http://localhost:3001/cimi/machine_images/a10f0123-ca40-4428-adac-26ac42f282dd</id> <name>a10f0123-ca40-4428-adac-26ac42f282dd</name> <description>Workshop template</description> <created>2012-10-11 11:20:26 +0200</created> <imageLocation href="rhevm://a10f0123-ca40-4428-adac-26ac42f282dd" /> </MachineImage> </Collection>

Create VM (Create Machine)

Request
In the request we use the URI of the machines collection, using HTTP POST, and passing body that contains the new machine details.
HTTP POST http://localhost:3001/cimi/machines <Machine> <name>cimi_machine</name> <description>My first machine!</description> <machineTemplate> <machineConfig href="http://localhost:3001/cimi/machine_configurations/SERVER"/> <machineImage href="http://localhost:3001/cimi/machine_images/a10f0123-ca40-4428-adac-26ac42f282dd"/> </machineTemplate> </Machine>

Response

<Machine xmlns="http://schemas.dmtf.org/cimi/1"> <id>http://localhost:3001/cimi/machines/1bac66da-7ecc-4e19-bc91-0623c5448fc9</id> <name>1bac66da-7ecc-4e19-bc91-0623c5448fc9</name> <description>cimi_machine</description> <created>2012-10-11T11:52:40.257+02:00</created> <property name="machine_image"> http://localhost:3001/cimi/machine_images/a10f0123-ca40-4428-adac-26ac42f282dd </property> <property name="credential"> http://localhost:3001/cimi/credentials </property> <state>PENDING</state> <cpu>2</cpu> <memory>1048576</memory> <disks href="http://localhost:3001/cimi/machines/1bac66da-7ecc-4e19-bc91-0623c5448fc9/disks" /> <volumes href="http://localhost:3001/cimi/machines/1bac66da-7ecc-4e19-bc91-0623c5448fc9/volumes" /> <networkInterfaces href="http://localhost:3001/cimi/machines/1bac66da-7ecc-4e19-bc91-0623c5448fc9/network_interfaces" /> </Machine>

Get VM (Get Machine)

Request

HTTP GET http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2

Response

<Machine xmlns="http://schemas.dmtf.org/cimi/1"> <id>http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2</id> <name>7434e6e3-a85d-4bfb-b952-b191288c2aa2</name> <description>cimi_machine</description> <created>2012-10-18T14:22:57.675+02:00</created> <property name="machine_image"> http://localhost:3001/cimi/machine_images/a10f0123-ca40-4428-adac-26ac42f282dd </property> <property name="credential">http://localhost:3001/cimi/credentials</property> <state>STOPPED</state> <cpu>2</cpu> <memory>1048576</memory> <disks href="http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2/disks"> <id>http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2/disks</id> <count>1</count> <Disk> <id>http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2 /disks/7434e6e3-a85d-4bfb-b952-b191288c2aa2_disk_1024</id> <name>7434e6e3-a85d-4bfb-b952-b191288c2aa2_disk_1024</name> <description>DiskCollection for Machine 7434e6e3-a85d-4bfb-b952-b191288c2aa2</description> <created>2012-10-18T14:22:57.675+02:00</created> <capacity>1024</capacity> </Disk> </disks> <volumes href="http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2/volumes" /> <operation rel="http://schemas.dmtf.org/cimi/1/action/start" href="http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2/start" /> <operation rel="http://schemas.dmtf.org/cimi/1/action/destroy" href="http://localhost:3001/cimi/machines/7434e6e3-a85d-4bfb-b952-b191288c2aa2" /> </Machine>
Note that the list of operations that one can do on a machine changes according to its status. Now that it is STOPPED, you can wither start or destroy it. When creating the machine (in the previous example), it was in PENDING status, so no operations were available.

Start VM (Start Machine)

Request
In the request we use the URI of the specific machine, followed by "start", with an action body.
HTTP POST http://localhost:3001/cimi/machines/81e0908a-04da-4859-8a92-f80d071a2e4c/start <Action> <action>http://www.dmtf.org/cimi/action/start</action> </Action>

Response
The response is just HTTP code 200, which means that a start action was triggered. One needs to go HTTP GET on the machine resource to monitor for its progress.

Stop VM (Stop Machine)

Request
In the request we use the URI of the specific machine, followed by "stop", with an action body.
HTTP POST http://localhost:3001/cimi/machines/81e0908a-04da-4859-8a92-f80d071a2e4c/stop <Action> <action>http://www.dmtf.org/cimi/action/stop</action> </Action>

Response
The response is just HTTP code 200, which means that a stop action was triggered. One needs to go HTTP GET on the machine resource to monitor for its progress.

Delete VM (Delete Machine)

Request
In the request we use the URI of the specific machine, using HTTP DELETE.
HTTP DELETE http://localhost:3001/cimi/machines/81e0908a-04da-4859-8a92-f80d071a2e4c

Response
The response is just HTTP code 200, which means that a delete action was triggered. One needs to go HTTP GET on the machines collection (or the machine itself), so see that it was indeed deleted.

Summary

The oVirt engine is a strong IaaS platform, and it is useful to use this platform using standard APIs, such as EC2 and CIMI. By using Deltacloud, supporting these APIs can be achieved very easily. There is still more work to be done to give better integration between Deltacloud and the oVirt engine, but the basics are there, allowing to use oVirt via standard APIs.