OCCI Service Usage Guide 2.0

The OpenNebula OCCI API is a RESTful service to create, control and monitor cloud resources based on the latest draft of the OGF OCCI API specification. Interactions with the resources are done through HTTP verbs (GET, POST, PUT and DELETE).

OCCI Resources

There are three kind of resources, listed below with their implemented methods:

  • Storage:
    • Upload: using a multi-part HTTP POST.
    • Retrieve: using a HTTP GET.
  • Network:
    • Upload: using a HTTP POST.
    • Retrieve: using a HTTP GET.
  • Compute:
    • Upload: using a HTTP POST.
    • Update: using a HTTP PUT.
    • Retrieve: using a HTTP GET.

Collections of resources have the following implemented methods for all Pool Resources are:

  • POST: Creates a new resource within the colletion, with the representation in the POST body.
  • GET: Retrieves the representation of the collection.

User Account Configuration

An account is needed in order to use the OpenNebula OCCI cloud. The cloud administrator will be responsible for assigning these accounts, which have a one to one correspondence with OpenNebula accounts, so all the cloud administrator has to do is check the configuration guide to setup accounts, and automatically the OpenNebula OCCI cloud account will be created.

In order to use such an account, the end user can make use of clients programmed to access the services described in the previous section. For this, she has to set up her environment, particularly the following aspects:

  • Authentication: This can be achieved in two different ways, here listed in order of priority (i.e. values specified in the argument line supersede environmental variables)
    • Using the commands arguments. All the commands accept a username (as the OpenNebula username) and a password (as the OpenNebula password)
    • If the above is not available, the ONE_AUTH variable will be checked for authentication (with the same used for OpenNebula CLI, pointing to a file containing a single line: “username:password”).
  • Server location: The command need to know where the OpenNebula OCCI service is running. You can pass the OCCI service endpoint using the ”–url” flag in the commands. If that is not present, the OCCI_URL environment variable is used (in the form of a http URL, including the port if it is not the standard 80). Again, if the OCCI_URL variable is not present, it will default to “http://localhost:4567

:!: The OCCI_URL has to use the FQDN of the OCCI Service

Hello OCCI Cloud!

Lets take a walk through a typical usage scenario. In this brief scenario it will be shown how to upload an image to the OCCI OpenNebula Storage repository, how to create a Network in the OpenNebula OCCI cloud and how to create Compute resource using the image and the network previously created.

  • Storage

Assuming we have a working Gentoo installation residing in an .img file, we can upload it into the OpenNebula OCCI cloud using the following OCCI representation of the image:

    <STORAGE>
        <NAME>Ubuntu Desktop</NAME>
        <DESCRIPTION>Ubuntu 10.04 desktop for students.</DESCRIPTION>
        <TYPE>OS</TYPE>
        <URL>file:///images/ubuntu/jaunty.img</URL>
    </STORAGE>

Next, using the occi-storage command we will create the Storage resource:

$ ./occi-storage --url http://localhost:4567 --username oneadmin --password opennebula create imagexml
<STORAGE href='http://localhost:4567/storage/1'>
    <ID>1</ID>
    <NAME>Ubuntu Desktop/NAME>
    <TYPE>OS/TYPE>
    <DESCRIPTION>Ubuntu 10.04 desktop for students.</DESCRIPTION>
    <SIZE>41943040</SIZE>
</STORAGE>

The user should take note of this ID, as it will be needed to add it to the Compute resource.

  • Network

The next step would be to create a Network resource

    <NETWORK>
	<NAME>MyServiceNetwork</NAME>
	<ADDRESS>192.168.1.1</ADDRESS>
	<SIZE>200</SIZE>
    </NETWORK>

Next, using the occi-network command we will create the Network resource:

$ ./occi-network --url http://localhost:4567 --username oneadmin --password opennebula create vnxml 
<NETWORK href='http://localhost:4567/network/0'>
    <ID>0</ID>
    <NAME>MyServiceNetwork</NAME>
    <ADDRESS>192.168.1.1/ADDRESS>
    <SIZE>200/SIZE>
</NETWORK>

  • Compute

The last step would be to create a Compute resource referencing the Storage and Networks resource previously created by means of their ID, using a representation like the following:

    <COMPUTE>
        <NAME>MyCompute</NAME>
        <INSTANCE_TYPE>small</INSTANCE_TYPE>
        <DISK>
            <STORAGE href="http://www.opennebula.org/storage/1"/>
        </DISK>
        ...
        <NIC>
            <NETWORK href="http://www.opennebula.org/network/0"/>
            <IP>192.168.0.12</IP>
        </NIC>
        ...
        <CONTEXT>
            <HOSTNAME>MAINHOST</HOSTNAME>
            <DATA>DATA1</DATA>
        </CONTEXT>
    </COMPUTE>

Next, using the occi-compute command we will create the Compute resource:

$ ./occi-compute --url http://localhost:4567 --username oneadmin --password opennebula create ~/vmxml 
<COMPUTE href='http://localhost:4567/compute/8'>
    <ID>8</ID>
    <NAME>vm example</NAME>
    <STATE>STOPPED/STATE>
    <DISK>
        <STORAGE href='http://localhost:4567/storage/1' name='ttylinux'/>
        <TYPE>DISK/TYPE>
        <TARGET>hda</TARGET>
    </DISK>
    <NIC>
        <NETWORK href='http://localhost:4567/network/0' name='Private LAN'/>
        <IP>192.168.0.12</IP>
        <MAC>02:00:0a:00:00:06</MAC>
    </NIC>
    <CONTEXT>
        <HOSTNAME>MAINHOST</HOSTNAME>
        <DATA>DATA1</DATA>
    </CONTEXT>
</COMPUTE>

If we want to stop the Compute resource:

    <COMPUTE>
        <ID>8</ID>
        <STATE>STOPPED</STATE>
    </COMPUTE>

Next, using the occi-compute command we will update the Compute resource:

$ ./occi-compute --url http://localhost:4567 --username oneadmin --password opennebula update ~/updatexml 
<COMPUTE href='http://localhost:4567/compute/8'>
    <ID>8</ID>
    <NAME>vm example</NAME>
    <STATE>STOPPED/STATE>
    <DISK>
        <STORAGE href='http://localhost:4567/storage/1' name='ttylinux'/>
        <TYPE>DISK/TYPE>
        <TARGET>hda</TARGET>
    </DISK>
    <NIC>
        <NETWORK href='http://localhost:4567/network/0' name='Private LAN'/>
        <IP>192.168.0.12</IP>
        <MAC>02:00:0a:00:00:06</MAC>
    </NIC>
    <CONTEXT>
        <HOSTNAME>MAINHOST</HOSTNAME>
        <DATA>DATA1</DATA>
    </CONTEXT>
</COMPUTE>

:!: You can obtain more information on how to use the above commands accessing their Usage help passing them the -h flag. For instance, a -T option is available to set a connection timeout.

:!: In platforms where 'curl' is not available or buggy (i.e. CentOS), a '-M' option is available to perform upload using the native ruby Net::HTTP using http multipart