Welcome to ooi’s documentation!

ooi is an implementation the Open Grid Forum’s Open Cloud Computing Interface (OCCI) for OpenStack.

User documentation

User documentation

Please, read the following documentation if you intend to deploy ooi in your infrastructure.

Installation

Installation via packages

ooi packages are released through the EGI’s AppDB. In the ooi middleware page you will find the latest production and release candidates, as long as the repositories for the major GNU/Linux distributions.

Instalation from pip

ooi can be installed via pip from OpenStack Kilo onwards. If you are running Juno, the code will still work, but there are some dependencies that may be in conflict with the existing Python modules in your system, as long as missing dependencies (oslo.log is not available in Juno):

$ pip install ooi

Configuration

ooi configuration

ooi needs to be enabled in the OpenStack Compute configuration file. Append ooi to your enabled_apis option:

enabled_apis=ec2,osapi_compute,metadata,ooi

Moreover, the following options are available:

  • ooi_listen: IP address where ooi will listen. Defaults to 0.0.0.0
  • ooi_listen_port: Port ooi will bind to. Defaults to 8787.
  • ooi_workers: Number of workers to spawn, by default it is set to the number of CPUs in the node.
  • neutron_ooi_endpoint: Neutron endpoint, configures the network management by using neutron. If this is not set, the system will use nova-network.
Paste Configuration
TL;DR.

Add the corresponding Paste configuration according to your OpenStack version from Pipeline examples into your Paste configuration file (usually /etc/nova/api-paste.ini).

Detailed instructions

First it is needed to add the OCCI filter like this:

[filter:occi]
paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory
openstack_version = /v2

openstack_version can be configured to any of the supported OpenStack API versions, as indicated in Table Supported OpenStack API versions. If it is not configured, by default it will take the /v2.1 value.

Supported OpenStack API versions
OpenStack API version openstack_version reference OpenStack composite section
v2 /v2 [composite:openstack_compute_api_v2]
v2.1 /v2.1 [composite:openstack_compute_api_v21]

The next step is to create a composite section for the OCCI interface. It is needed to duplicate the corresponding OpenStack API ``composite`` section, renaming it to occi_api_v11. Once duplicated, the occi middleware needs to be added just before the last component of the pipeline. So, in the example above where /v2 has been configured, we need to duplicate the [composite:openstack_compute_api_v2] as follows:

[composite:occi_api_11]
use = call:nova.api.auth:pipeline_factory
noauth = compute_req_id faultwrap sizelimit noauth ratelimit occi osapi_compute_app_v2
keystone = compute_req_id faultwrap sizelimit occi authtoken keystonecontext ratelimit occi osapi_compute_app_v2
keystone_nolimit = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v2

The last step regarding the API configuration is to add it to create the [composite:ooi] section:

[composite:ooi]
use = call:nova.api.openstack.urlmap:urlmap_factory
/occi1.1: occi_api_11

Finally, you need to enable it in the OpenStack nova configuration, so that it is loaded properly. Add ooi to the enabled_apis option in the configuration file and adapt the port if needed, via the ooi_listen_port (by default it listens in the 8787 port). On the other hand, network management by using neutron can be configure via the neutron_ooi_endpoint option (if it is not set, the system will use nova-network):

enabled_apis=ec2,osapi_compute,metadata,ooi
ooi_listen_port=8787
neutron_ooi_endpoint=http://127.0.0.1:9696/v2.0

OpenStack has two components to support network management. On one side, nova-network provides a simple network management which creates, lists, shows information for, and deletes networks. Admin permissions are required to create and delete networks. On the other side, the neutron component allows to manage and configure advanced network features. OOI implements the OCCI interface to simple network management by using either nova-network or neutron. neutron_ooi_endpoint configures the neutron endpoint. It is an optional parameter that configures the network management by using neutron. If this is not set, the system will use nova-network.

If everything is OK, after rebooting the nova-api service you should be able to access your OCCI endpoint at:

$ nova credentials
# Grab the token
$ export KID=<token>
$ curl -H "x-auth-token: $KID" http://localhost:8787/occi1.1/-/

Usage documentation

Discovery

In order to discover the available resources in the system, OOI provides a view of the relevant resources for its usage:

curl -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/-/

It will show the OCCI and OpenStack resources related to OOI.

Compute

It allows to create, list, show and delete VMs.

List compute

It lists VMs:

curl  -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/compute

It returns a HTTP 200 with output:

X-OCCI-Location: http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624
X-OCCI-Location: http://127.0.0.23:8787/occi1.1/compute/0ce5df96-7e61-4a8e-b821-9ebb88e77e07
Show compute

It shows details of a VM:

curl -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624

It returns a HTTP 200 with output:

Category: compute; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind"; title="compute resource"; rel="http://schemas.ogf.org/occi/core#resource"; location="http://127.0.0.23:8787/occi1.1/compute/"
Category: 5f4311da-2ee2-47a6-913b-5d8496486c62; scheme="http://schemas.openstack.org/template/os#"; class="mixin"; title="cirros-0.3.4-x86_64-uec"; rel="http://schemas.ogf.org/occi/infrastructure#os_tpl"; location="http://127.0.0.23:8787/occi1.1/os_tpl/5f4311da-2ee2-47a6-913b-5d8496486c62"
Category: 42; scheme="http://schemas.openstack.org/template/resource#"; class="mixin"; title="Flavor: m1.nano"; rel="http://schemas.ogf.org/occi/infrastructure#resource_tpl"; location="http://127.0.0.23:8787/occi1.1/resource_tpl/42"
X-OCCI-Attribute: occi.core.title="vm_assig_2"
X-OCCI-Attribute: occi.compute.state="inactive"
X-OCCI-Attribute: occi.compute.memory=64
X-OCCI-Attribute: occi.compute.cores=1
X-OCCI-Attribute: occi.compute.hostname="vm_assig_2"
X-OCCI-Attribute: occi.core.id="703910d7-97f7-4e3e-9243-30830591f624"
Link: <http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624?action=start>; rel="http://schemas.ogf.org/occi/infrastructure/compute/action#start"
Link: <http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624?action=stop>; rel="http://schemas.ogf.org/occi/infrastructure/compute/action#stop"
Link: <http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624?action=restart>; rel="http://schemas.ogf.org/occi/infrastructure/compute/action#restart"
Link: <http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624?action=suspend>; rel="http://schemas.ogf.org/occi/infrastructure/compute/action#suspend"
Link: <http://127.0.0.23:8787/occi1.1/networklink/703910d7-97f7-4e3e-9243-30830591f624_cd48b7dd-9ac8-44fc-aec0-5ea679941ced_12.0.0.87>;
rel="http://schemas.ogf.org/occi/infrastructure#network";
self="http://127.0.0.23:8787/occi1.1/networklink/703910d7-97f7-4e3e-9243-30830591f624_cd48b7dd-9ac8-44fc-aec0-5ea679941ced_12.0.0.87";
occi.networkinterface.mac="fa:16:3e:20:14:f2"; occi.networkinterface.interface="eth0"; occi.networkinterface.state="active";
occi.networkinterface.allocation="dynamic"; occi.networkinterface.address="12.0.0.87";
occi.core.source="http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624";
occi.core.target="http://127.0.0.23:8787/occi1.1/network/cd48b7dd-9ac8-44fc-aec0-5ea679941ced";
occi.core.id="703910d7-97f7-4e3e-9243-30830591f624_cd48b7dd-9ac8-44fc-aec0-5ea679941ced_12.0.0.87"
Link: <http://127.0.0.23:8787/occi1.1/networklink/703910d7-97f7-4e3e-9243-30830591f624_PUBLIC_11.0.0.44>;
rel="http://schemas.ogf.org/occi/infrastructure#network"; self="http://127.0.0.23:8787/occi1.1/networklink/703910d7-97f7-4e3e-9243-30830591f624_PUBLIC_11.0.0.44";
occi.networkinterface.mac="fa:16:3e:20:14:f2"; occi.networkinterface.interface="eth0"; occi.networkinterface.state="active"; occi.networkinterface.allocation="dynamic";
occi.networkinterface.address="11.0.0.44"; occi.core.source="http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624";
occi.core.target="http://127.0.0.23:8787/occi1.1/network/PUBLIC"; occi.core.id="703910d7-97f7-4e3e-9243-30830591f624_PUBLIC_11.0.0.44"
Link: <http://127.0.0.23:8787/occi1.1/storagelink/703910d7-97f7-4e3e-9243-30830591f624_f551d92d-1992-4625-91ff-5e48d96d03c9>;
rel="http://schemas.ogf.org/occi/infrastructure#storage";
self="https://127.0.0.23:8787/occi1.1/storagelink/703910d7-97f7-4e3e-9243-30830591f624_f551d92d-1992-4625-91ff-5e48d96d03c9";
occi.storagelink.deviceid="/dev/xvdb"; occi.core.source="https://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624";
occi.core.target="https://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9";
occi.core.id="703910d7-97f7-4e3e-9243-30830591f624_f551d92d-1992-4625-91ff-5e48d96d03c9"
Create compute

It creates a VM using the default resources, including links to storage and private networks:

curl -X POST http://127.0.0.23:8787/occi1.1/compute/ \
    -H 'X-Auth-Token: '$OS_TOKEN \
    -H 'Category: compute; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind", \
        5f4311da-2ee2-47a6-913b-5d8496486c62; scheme="http://schemas.openstack.org/template/os#"; class="mixin", \
        2; scheme="http://schemas.openstack.org/template/resource#"; class="mixin"' \
    -H 'Content-Type: text/occi' -H 'X-OCCI-Attribute: occi.core.title="OOI_VM_1"'

Also we can specify the network to be linked:

curl -X POST http://127.0.0.23:8787/occi1.1/compute/ \
    -H 'X-Auth-Token: '$OS_TOKEN \
    -H 'Category: compute; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind", \
        5f4311da-2ee2-47a6-913b-5d8496486c62; scheme="http://schemas.openstack.org/template/os#"; class="mixin", \
        2; scheme="http://schemas.openstack.org/template/resource#"; class="mixin"' \
    -H 'Link: </bar>; rel="http://schemas.ogf.org/occi/infrastructure#network"; \
        occi.core.target="http://127.0.0.23:8787/occi1.1/network/f8186fda-a389-468b-9c13-24b8eda65d77"' \
    -H 'Content-Type: text/occi' -H 'X-OCCI-Attribute: occi.core.title="OOI_VM_1"'

Links to storage can be also specified:

curl -X POST http://127.0.0.23:8787/occi1.1/compute/ \
    -H 'X-Auth-Token: '$OS_TOKEN \
    -H 'Category: compute; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind", \
        5f4311da-2ee2-47a6-913b-5d8496486c62; scheme="http://schemas.openstack.org/template/os#"; class="mixin", \
        2; scheme="http://schemas.openstack.org/template/resource#"; class="mixin"' \
    -H 'Link: </bar>; rel="http://schemas.ogf.org/occi/infrastructure#storage"; \
        occi.core.target="http://127.0.0.23:8787/occi1.1/storage/567ed104-3ddf-11e6-ad65-00219702a0b8"' \
    -H 'Content-Type: text/occi' -H 'X-OCCI-Attribute: occi.core.title="OOI_VM_1"'

It returns a HTTP 201 with output:

X-OCCI-Location: http://127.0.0.23:8787/occi1.1/compute/4a7dc666-33d2-495e-93fe-ccd224c98c11
Delete compute

It deletes a VM, including all the links associated to it:

curl -X DELETE -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/compute/703910d7-97f7-4e3e-9243-30830591f624

It returns a 204 empty response.

Storage

Storage management provides list, show, create and deletion of volumes to a specific tenant.

List storage

It lists volumes:

curl  -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/storage

It returns a HTTP 200 with output:

X-OCCI-Location: http://127.0.0.23:8787/occi1.1/storage/91bb7532-3ddb-11e6-9770-00219702a0b8
X-OCCI-Location: http://127.0.0.23:8787/occi1.1/storage/a10abe94-3ddb-11e6-bc5d-00219702a0b8
Show storage

It shows details of a volume:

curl -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9

It returns a HTTP 200 with output:

Category: storage; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind"; title="compute resource"; rel="http://schemas.ogf.org/occi/core#resource"; location="http://127.0.0.23:8787/occi1.1/storage/"
X-OCCI-Attribute: occi.storage.state="online"
X-OCCI-Attribute: occi.core.id="f551d92d-1992-4625-91ff-5e48d96d03c9"
X-OCCI-Attribute: occi.storage.size=1
X-OCCI-Attribute: occi.core.title="vol1"
Link: <http://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9?action=online>; rel="http://schemas.ogf.org/occi/infrastructure/storage/action#online"
Link: <http://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9?action=offline>; rel="http://schemas.ogf.org/occi/infrastructure/storage/action#offline"
Link: <http://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9?action=backup>; rel="http://schemas.ogf.org/occi/infrastructure/storage/action#backup"
Link: <http://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9?action=snapshot>; rel="http://schemas.ogf.org/occi/infrastructure/storage/action#snapshot"
Link: <http://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9?action=resize>; rel="http://schemas.ogf.org/occi/infrastructure/storage/action#resize"
Delete storage

It deletes a volume, including all the links associated to it:

curl -X DELETE -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/storage/f551d92d-1992-4625-91ff-5e48d96d03c9

It returns a 204 empty response.

Network

Network management provides list, show, create and deletion of networks to a specific tenant.

List networks

It lists all networks available for connecting virtual machines:

curl -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/network

It returns a HTTP 200 with output:

X-OCCI-Location: http://127.0.0.23:8787/occi1.1/network/2c9868b4-f71a-45d2-ba8c-dbf42f0b3120
X-OCCI-Location: http://127.0.0.23:8787/occi1.1/network/4213c7ef-68d4-42e8-a3cd-1c5bab3abe6
X-OCCI-Location: http://127.0.0.23:8787/occi1.1/network/PUBLIC
Show network

It shows the network features:

curl -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/network/b8a3d813-65da-4910-a80c-f97b4ba31fd4

It returns a HTTP 200 with output:

Category: network; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind"; title="network resource";
 rel="http://schemas.ogf.org/occi/core#resource"; location="http://127.0.0.23:8787/occi1.1/network/"
Category: ipnetwork; scheme="http://schemas.ogf.org/occi/infrastructure/network#"; class="mixin";
 title="IP Networking Mixin"
Category: osnetwork; scheme="http://schemas.openstack.org/infrastructure/network#"; class="mixin";
 title="openstack network"
X-OCCI-Attribute: occi.network.address="20.0.0.0/24"
X-OCCI-Attribute: occi.network.state="active"
X-OCCI-Attribute: occi.core.title="CommandLineOCCI"
X-OCCI-Attribute: occi.network.gateway="20.0.0.1"
X-OCCI-Attribute: occi.core.id="4a7dc666-33d2-495e-93fe-ccd224c98c11"
Link: <http://127.0.0.23:8787/occi1.1/network/4a7dc666-33d2-495e-93fe-ccd224c98c11?action=up>;
 rel="http://schemas.ogf.org/occi/infrastructure/network/action#up"
Link: <http://127.0.0.23:8787/occi1.1/network/4a7dc666-33d2-495e-93fe-ccd224c98c11?action=down>;
rel="http://schemas.ogf.org/occi/infrastructure/network/action#down"
Create network

It creates a network:

curl -X POST http://127.0.0.23:8787/occi1.1/network/ \
    -H 'X-Auth-Token: '$OS_TOKEN \
    -H 'Category: network; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind", \
        ipnetwork; scheme="http://schemas.ogf.org/occi/infrastructure/network#"; class="mixin"' \
    -H 'Content-Type: text/occi' \
    -H 'X-OCCI-Attribute: occi.core.title="OCCI_NET", occi.network.address="15.0.0.0/24"'

It returns a HTTP 201 with output:

X-OCCI-Location: http://127.0.0.23:8787/occi1.1/network/4a7dc666-33d2-495e-93fe-ccd224c98c11
Delete network

It deletes a network:

curl -X DELETE -H "X-Auth-token: "$OS_TOKEN http://127.0.0.23:8787/occi1.1/network/cb94496e-7e8e-4cb6-841d-30f38bc375e6

It returns a 204 empty response.

Pipeline examples

For your convenience, find below some example pipelines to be used with the corresponding OpenStack Compute version. These are to be added into your /etc/nova/api-paste.ini configuration file.

Juno (2014.2)
[composite:ooi]
use = call:nova.api.openstack.urlmap:urlmap_factory
/occi1.1: occi_api_11

[filter:occi]
paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory
openstack_version = /v2.0

[composite:occi_api_11]
[composite:openstack_compute_api_v2]
use = call:nova.api.auth:pipeline_factory
noauth = compute_req_id faultwrap sizelimit noauth ratelimit occi osapi_compute_app_v2
keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext ratelimit occi osapi_compute_app_v2
keystone_nolimit = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v2
Kilo (2015.1)
[composite:ooi]
use = call:nova.api.openstack.urlmap:urlmap_factory
/occi1.1: occi_api_11

[filter:occi]
paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory
openstack_version = /v2.1

[composite:occi_api_11]
use = call:nova.api.auth:pipeline_factory_v21
noauth = compute_req_id faultwrap sizelimit noauth occi osapi_compute_app_v21
noauth2 = compute_req_id faultwrap sizelimit noauth2 occi osapi_compute_app_v21
keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v21
Juno (2014.2)
[composite:ooi]
use = call:nova.api.openstack.urlmap:urlmap_factory
/occi1.1: occi_api_11

[filter:occi]
paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory
openstack_version = /v2.0

[composite:occi_api_11]
[composite:openstack_compute_api_v2]
use = call:nova.api.auth:pipeline_factory
noauth = compute_req_id faultwrap sizelimit noauth ratelimit occi osapi_compute_app_v2
keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext ratelimit occi osapi_compute_app_v2
keystone_nolimit = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v2
Kilo (2015.1)
[composite:ooi]
use = call:nova.api.openstack.urlmap:urlmap_factory
/occi1.1: occi_api_11

[filter:occi]
paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory
openstack_version = /v2.1

[composite:occi_api_11]
use = call:nova.api.auth:pipeline_factory_v21
noauth = compute_req_id faultwrap sizelimit noauth occi osapi_compute_app_v21
noauth2 = compute_req_id faultwrap sizelimit noauth2 occi osapi_compute_app_v21
keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v21
Liberty (2015.2)
[composite:ooi]
use = call:nova.api.openstack.urlmap:urlmap_factory
/occi1.1: occi_api_11

[filter:occi]
paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory
openstack_version = /v2.1

[composite:occi_api_11]
use = call:nova.api.auth:pipeline_factory_v21
noauth2 = compute_req_id faultwrap sizelimit noauth2 occi osapi_compute_app_v21
keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v21

Developer documentation

Developer documentation

ooi’s modules

Indices and tables