OpenNebula OCCI Specification 3.2

Resources

The OpenNebula OCCI API is a RESTful service to create, control and monitor cloud resources using an implementation of the OGF OCCI API specification based on the draft 0.8. This implementation also includes some extensions, requested by the community, to support OpenNebula specific functionality. There are two types of resources that resemble the basic entities managed by the OpenNebula system, namely:

  • Pool Resources (PR): Represents a collection of elements owned by a given user. In particular five pool resources are defined: COMPUTE_COLLECTION, INSTANCE_TYPE_COLLECTION, NETWORK_COLLECTION and STORAGE_COLLECTION.
  • Entry Resources (ER): Represents a single entry within a given collection: COMPUTE, NETWORK and STORAGE.

A COMPUTE entry resource can be linked to one or more STORAGE or NETWORK resources and one INSTANCE_TYPE.

Methods

The methods associated with each resource type are as follows:

  • Pool Resources (PR)
    • GET: to list all the entry resources in that pool resource owned by the user
    • POST: to create a new entry resource
  • Entry Resources (ER)
    • GET: to list the information associated with that resource
    • PUT: to update the resource
    • DELETE: to delete the resource

The Pool Resources

The root element required for all the PRs is named after the pool name, eg. COMPUTE_COLLECTION, INSTANCE_TYPE_COLLECTION, NETWORK_COLLECTION or STORAGE_COLLECTION (note that XML tags are upper case). No attributes can be defined for the root element.

Each one of ERs in the pool are described by an element (e.g. COMPUTE, INSTANCE_TYPE, NETWORK or STORAGE) with one attribute:

  • href, a URI for the ER

Example:

  • Compute Collection
    <COMPUTE_COLLECTION>
        <COMPUTE href="http://www.opennebula.org/compute/310" name="TestVM"/>
        <COMPUTE href="http://www.opennebula.org/compute/432" name="Server1"/>
        <COMPUTE href="http://www.opennebula.org/compute/123" name="Server2"/>
    </COMPUTE_COLLECTION>
  • Instance Type Collection
    <INSTANCE_TYPE_COLLECTION>
	<INSTANCE_TYPE href="http://0.0.0.0:4567/instance_type/large">
	    <NAME>large</NAME>
	    <CPU>8</CPU>
	    <MEMORY>8192</MEMORY>
	</INSTANCE_TYPE>
	<INSTANCE_TYPE href="http://0.0.0.0:4567/instance_type/small">
	    <NAME>small</NAME>
	    <CPU>1</CPU>
    	    <MEMORY>1024</MEMORY>
    	</INSTANCE_TYPE>
    	<INSTANCE_TYPE href="http://0.0.0.0:4567/instance_type/medium">
    	    <NAME>medium</NAME>
    	    <CPU>4</CPU>
    	    <MEMORY>4096</MEMORY>
    	</INSTANCE_TYPE>
    </INSTANCE_TYPE_COLLECTION>
  • Network Collection
    <NETWORK_COLLECTION>
        <NETWORK href="http://www.opennebula.org/network/310" name="Private_LAN"/>
        <NETWORK href="http://www.opennebula.org/network/432" name="Public_IPS"/>
    </NETWORK_COLLECTION>
  • Storage Collection
    <STORAGE_COLLECTION>
        <STORAGE href="http://www.opennebula.org/storage/310" name="Ubuntu10.04"/>
        <STORAGE href="http://www.opennebula.org/storage/432" name="CentOS6"/>
    </STORAGE_COLLECTION>

The Network Resource

The NETWORK element defines a virtual network that interconnects those COMPUTES with a network interface card attached to that network. The traffic of each network is isolated from any other network, so it constitutes a broadcasting domain.

The following elements can be defined for a NETWORK:

  • ID, the uuid of the network
  • NAME, describing the network
  • ADDRESS, of the network
  • SIZE, of the network, defaults to C

Example:

    <NETWORK href="http://www.opennebula.org/network/123">
         <ID>123</ID>
         <NAME>BlueNetwork</NAME>
         <ADDRESS>192.168.0.1</ADDRESS>
         <SIZE>C</SIZE>
    </NETWORK>

The Storage Resource

The STORAGE is a resource containing an operative system or data, to be used as a virtual machine disk:

  • ID, the uuid of the image
  • NAME, name of the image
  • DESCRIPTION, describing the image
  • TYPE, type of the image
    • OS: contains a working operative system
    • CDROM: readonly data
    • DATABLOCK: storage for data, which can be accessed and modified from different Computes
  • SIZE, of the image in MBs
  • FSTYPE, in case of DATABLOCK, the type of filesystem desired

Example:

    <STORAGE href="http://www.opennebula.org/storage/123">
        <ID>123</ID>
        <NAME>Ubuntu Desktop</NAME>
        <DESCRIPTION>UUbuntu 10.04 desktop for students.</DESCRIPTION>
        <TYPE>OS</TYPE>
        <SIZE>2048</SIZE>
    </STORAGE>

The Compute Resource

The COMPUTE element defines a virtual machine by specifying its basic configuration attributes such as NIC or DISK. The following elements can be defined:

  • ID, the uuid of the virtual machine.
  • NAME, describing the virtual machine.
  • TYPE, a COMPUTE type specifies a CPU and memory capacity, valid types are small, medium and large.
  • STATE, the state of the COMPUTE. This can be changed to
    • INIT
    • PENDING
    • HOLD
    • ACTIVE
    • STOPPED
    • SUSPENDED
    • DONE
    • FAILED
  • DISK, the block devices attached to the virtual machine.
  • NIC, the network interfaces.

Example:

    <COMPUTE href="http://www.opennebula.org/compute/32">
        <ID>32</ID>
        <NAME>Web Server</NAME>
        <INSTANCE_TYPE href="http://0.0.0.0:4567/instance_type/small">small</INSTANCE_TYPE>
        <STATE>ACTIVE</STATE>
        <DISK>
            <STORAGE href="http://www.opennebula.org/storage/34" name="Ubuntu10.04"/>
            <TYPE>OS</TYPE>
            <TARGET>hda</TARGET>
            ...
        </DISK>
        <DISK>
            <STORAGE href="http://www.opennebula.org/storage/24" name="testingDB"/>
            <TYPE>CDROM</TYPE>
            <TARGET>hdc</TARGET>
            ...
        </DISK>
        ...
        <NIC>
            <NETWORK href="http://www.opennebula.org/network/12" name="Private_LAN"/>
            <MAC>00:ff:72:31:23:17</MAC>
            <IP>192.168.0.12</IP>
            ...
        </NIC>
        <NIC>
            <NETWORK href="http://www.opennebula.org/network/10" name="Public_IPs"/>
            <MAC>00:ff:72:17:20:27</MAC>
            <IP>192.168.0.25</IP>
            ...
        </NIC>
        ...
    </COMPUTE>

Authentication & Authorization

User authentication will be HTTP Basic access authentication to comply with REST philosophy. Authorization will be handled by OpenNebula's user management module, that currently works as:

  • There are normal users and one privilege user (known as oneadmin)
  • All users can access retrieve information of all PRs
  • All users can perform operations over all PRs
  • Normal users can perform operations over their ERs, but no over other users'
  • Privilege user oneadmin can perform operations over all ERs

HTTP Headers

The following headers are compulsory:

  • Content-Length: The size of the Entity Body in octets
  • Content-Type: application/xml

Uploading images needs HTTP multi part support, and also the following header

  • Content-Type: multipart/form-data

Return Codes

The OpenNebula Cloud API uses the following subset of HTTP Status codes:

  • 200 OK : The request has succeeded. The information returned with the response is dependent on the method used in the request, as follows:
    • GET an entity corresponding to the requested resource is sent in the response
    • POST an entity containing the result of the action
  • 201 Created : Request was successful and a new resource has being created
  • 202 Accepted : The request has been accepted for processing, but the processing has not been completed
  • 204 No Content : The request has been accepted for processing, but no info in the response
  • 400 Bad Request : Malformed syntax
  • 401 Unauthorized : Bad authentication
  • 403 Forbidden : Bad authorization
  • 404 Not Found : Resource not found
  • 500 Internal Server Error : The server encountered an unexpected condition which prevented it from fulfilling the request.
  • 501 Not Implemented : The functionality requested is not supported

The methods specified below are described without taking into account 4xx (can be inferred from authorization information in section above) and 5xx errors (which are method independent). HTTP verbs not defined for a particular entity will return a 501 Not Implemented.

Pool Resource Methods

Computes

Instance types

Networks

Storage

All the above resources share the same HTTP verb semantics:

Method Meaning / Entity Body Response
GET Request for the contents of the pool200 OK: An XML representation of the pool in the http body
POST Request for the creation of an ER. An XML representation of a VM without the ID element should be passed in the http body 201 Created: An XML representation of a ER of type COMPUTE with the ID

Entity Resource Methods

Network

Method Meaning / Entity Body Response
GET Request the representation of the network resource identified by <net_id>200 OK : An XML representation of the network in the http body
PUT Update request for a Network identified by <net_id> 202 Accepted : The update request is being process, polling required to confirm update
DELETE Deletes the Network resource identified by <net-id> 204 No Content: The Network has been successfully deleted

Storage

Method Meaning / Entity Body Response
GET Request the representation of the image resource identified by <storage_id>200 OK : An XML representation of the image in the http body
PUT Update request for a Storage identified by <storage_id> 202 Accepted : The update request is being process, polling required to confirm update
DELETE Deletes the Image resource identified by <storage_id>204 No Content : The image has been successfully deleted

Compute

Method Meaning / Entity Body Response
GET Request the representation of the Compute resource identified by <compute_id>200 OK : An XML representation of the Compute in the http body
PUT Update request for a Compute identified by <compute_id> 202 Accepted : The update request is being process, polling required to confirm update
DELETE Deletes the Compute resource identified by <compute_id>204 No Content : The Compute has been successfully deleted

Implementation Notes

Authentication

It is recommended that the server-client communication is performed over HTTPS to avoid sending user authentication information in plain text.

Notifications

HTTP protocol does not provide means for notification, so this API relies on asynchronous polling to find whether a VM update is successful or not.