index.rst 7.88 KB
Newer Older
John Giannelos's avatar
John Giannelos committed
1 2 3 4 5
.. snf-occi documentation master file, created by
   sphinx-quickstart on Mon Mar 26 13:45:54 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

6 7
About snf-occi
==============
John Giannelos's avatar
John Giannelos committed
8

9
**snf-occi** snf-occi implements the OCCI specification on top of Synnefo’s API in order to achieve greater interoperability in common tasks referring cyclades management. This module is a translation bridge between OCCI and the Openstack API and is designed to be as independent as possible from the rest IaaS, providing an OCCI compatibility layer to other services using Openstack API. 
John Giannelos's avatar
John Giannelos committed
10

11
**snf-occi** is based in modules provided by kamaki library-tool when dealing with REST API calls to Openstack.
John Giannelos's avatar
John Giannelos committed
12 13 14 15

.. toctree::
   :maxdepth: 2

16
About Open Cloud Computing Interface (OCCI)
17
-------------------------------------------
John Giannelos's avatar
John Giannelos committed
18
The current OCCI specification consists of the following three documents:
John Giannelos's avatar
John Giannelos committed
19 20 21 22 23

* `OCCI Core <http://ogf.org/documents/GFD.183.pdf>`_
* `OCCI Infrastructure <http://ogf.org/documents/GFD.184.pdf>`_
* `OCCI HTTP rendering <http://ogf.org/documents/GFD.185.pdf>`_

24 25
The master document for the OCCI specification is at `OCCI Specification <http://occi-wg.org/about/specification/>`_

John Giannelos's avatar
John Giannelos committed
26 27
OCCI and Cyclades
-----------------
28
The OCCI implementation for Cyclades is going to be based in the OCCI 1.1 Infrastructure specification, in which common Cloud IaaS components are described. The correspondence between OCCI and Cyclades is as follows:
John Giannelos's avatar
John Giannelos committed
29

John Giannelos's avatar
John Giannelos committed
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
+-------------------------+-------------------------+
|OCCI                     |Cyclades                 |
+=========================+=========================+
|Compute                  |Synnefo servers          |
+-------------------------+-------------------------+
|OS Template              |Synnefo images           |
+-------------------------+-------------------------+
|Resource Template        |Synnefo flavors          |
+-------------------------+-------------------------+
|Networking               |NA                       |
+-------------------------+-------------------------+
|Storage                  |NA                       |
+-------------------------+-------------------------+


John Giannelos's avatar
John Giannelos committed
45
 
46
**Note:** Metadata info in Synnefo's servers cannot be represented (clearly) using OCCI's components.
John Giannelos's avatar
John Giannelos committed
47 48


John Giannelos's avatar
John Giannelos committed
49
OCCI requirements
50
-----------------
John Giannelos's avatar
John Giannelos committed
51
Due to OCCI's structure there cannot be straightforward mapping to Cyclades/OpenStack API. The missing elements are networking and storage capabilities using current Cyclades API.
John Giannelos's avatar
John Giannelos committed
52

John Giannelos's avatar
John Giannelos committed
53 54
OCCI operations
****************
John Giannelos's avatar
John Giannelos committed
55

John Giannelos's avatar
John Giannelos committed
56
Below you can see the required procedures/operations for OCCI compatibility.
John Giannelos's avatar
John Giannelos committed
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
   
* Handling the query interface
   * Query interface must be found under path /-/
   * Retrieve all registered Kinds, Actions and Mixins
   * Add a mixin definition
   * Remove a mixin definition

* Operation on paths in the name-space 
   * Retrieving the state of the name-space hierarchy
   * Retrieving all Resource instances below a path
   * Deletion of all Resource instances below a path

* Operations on Mixins and Kinds
   * Retrieving all Resource instances belonging to Mixin or Kind
   * Triggering actions to all instances of a Mixin or a Kind
   * Associate resource instances with a Mixin or a Kind
   * Full update of a Mixin collection
   * Dissociate resource instances from a Mixin

* Operations on Resource instances
   * Creating a resource instance
   * Retrieving a resource instance
   * Partial update of a resource instance
   * Full update of a resource instance
   * Delete a resource instance
   * Triggering an action on a resource instance

John Giannelos's avatar
John Giannelos committed
84 85 86 87
* Handling Link instances
   * Inline creation of a Link instance
   * Retrieving Resource instances with defined Links
   * Creating of Link Resource instance
John Giannelos's avatar
John Giannelos committed
88 89 90 91 92


OCCI client/server library
==========================

93
pyssf is a collection of OCCI python modules. It aims to provide a high-level interface for the integration of OCCI to other new or existing applications. 
John Giannelos's avatar
John Giannelos committed
94 95 96 97 98

Features:
---------

* It includes a REST API service with the OCCI specifications already implemented
John Giannelos's avatar
John Giannelos committed
99
* It only requires a custom backend and registry to interact with Cyclades
John Giannelos's avatar
John Giannelos committed
100

101 102
Current progress
=================
103
By now we have considered implementing only the **Compute** backend of the OCCI to Cyclades/Openstack API bridge and we are planning to extend it for **networking** and **storage** capabilities. It is possible to implement the remaining capabilities directly for OCCI 1.2, though.
104 105 106

Installation
-------------
Stavros Sachtouris's avatar
Stavros Sachtouris committed
107
Install **snf-occi** API translation server by cloning our latest source code:
108

Stavros Sachtouris's avatar
Stavros Sachtouris committed
109
::
110

Stavros Sachtouris's avatar
Stavros Sachtouris committed
111 112 113 114
  git clone https://github.com/grnet/snf-occi
  cd snf-occi
  cp snfOCCI/config.py.template snfOCCI/config.py
  python setup.py install
115

116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
**NOTE**: edit the **config.py** before running the service. In the following
example, we replicate the settings of the hellasgrid service, but you can set
your own cloud and astavoms settings in your own deployment

::

  #  Copy this file as config.py and fill in the appropriate values
  
  COMPUTE = {
    'arch': 'x86',
  }
  
  KAMAKI = {
    'compute_url': 'https://cyclades.okeanos.grnet.gr/compute/v2.0/',
    'astakos_url': 'https://accounts.okeanos.grnet.gr/identity/v2.0',
    'network_url': 'https://cyclades.okeanos.grnet.gr/network/v2.0'
  }
  
  KEYSTONE_URL = 'https://okeanos-astavoms.hellasgrid.gr'
  HOSTNAME = 'https://okeanos-occi2.hellasgrid.gr:9000'
  PASTEDEPLOY = '/home/user/src/snf-occi/snfOCCI/paste_deploy/snf-occi-paste.ini'
137

Stavros Sachtouris's avatar
Stavros Sachtouris committed
138
snf-occi is a simple WSGI python application with basic paste support. A full scale deployment is out of the scope of this document, but it is expected to use standard tools like apache and gunicorn to setup the service.
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170

Examples:
---------
For the examples below we assume server is running on localhost (port 8888) and authentication token is $AUTH. For the HTTP requests we are using **curl**.

* Retrieve all registered Kinds, Actions and Mixins:

  ::

    curl -v -X GET localhost:8888/-/ -H 'Auth-Token: $AUTH'

* Create a new VM described by the flavor 'C2R2048D20' and using the image 'Debian'

  ::
 
    curl -v -X POST localhost:8888/compute/ 
    -H 'Category: compute; scheme=http://schemas.ogf.org/occi/infrastructure#;  class="kind";' 
    -H 'X-OCCI-Attribute: occi.core.title = newVM' -H 'Category: C2R2048D20; scheme=http://schemas.ogf.org/occi/infrastructure#; ' 
    -H 'Category: Debian; scheme=http://schemas.ogf.org/occi/infrastructure#;' -H 'Auth-Token: $AUTH' 
    -H 'Content-type: text/occi'

* Retrieve all the details of th VM with identifier $ID

  ::

    curl -v -X GET localhost:8888/compute/$ID -H 'Auth-Token: $AUTH'

* Delete the VM with identifier $ID

  ::
  
    curl -v -X DELETE localhost:8888/compute/$ID -H 'Auth-Token: $AUTH'
John Giannelos's avatar
John Giannelos committed
171

172 173
Testing
-------
Stavros Sachtouris's avatar
Stavros Sachtouris committed
174
Here is how to run a local paste server. This is useful only for experimenting
175 176
and development and should not be used in production. We suggest to run this
test in a sandboxed environment e.g., virtualenv
Stavros Sachtouris's avatar
Stavros Sachtouris committed
177 178 179

::

180 181 182
  virtualenv mytest
  source mytest/bin/activate
  pip install Paste PasteDeploy
Stavros Sachtouris's avatar
Stavros Sachtouris committed
183 184 185 186 187
  cp snfOCCI/paste_deploy/test-server.py .
  python test-server.py
    server is running on 127.0.0.1:8080

Follow the test/README.md instructions to setup a client e.g., with docker, and
188 189
test the application with the prepared queries or the examples of the current
document.
190 191 192 193 194

A smart way to test the application is by using the `egifedcloud/fedcloud-userinterface`. Make sure you have valid and authorized proxy certificates in your ${HOME}/.globus directory, and then start a cointainer shell loaded with all necessary client tools. E.g., to perform a "list servers" operation:

  ::

195
    $ docker run -v /home/user/.globus:/root/.globus -it egifedcloud/fedcloud-userinterface /bin/bash
196 197 198 199 200
    # fetch-crl -p 20
    # voms-proxy-init --voms fedcloud.egi.eu -rfc
      Your proxy is stored at /tmp/x509up_u0
    # occi --endpoint https://snf-occi.example.com --action list --resource compute -n x509 -x /tmp/x509up_u0 -X

John Giannelos's avatar
John Giannelos committed
201 202 203 204 205 206 207

Indices and tables
==================

* :ref:`genindex`
* :ref:`search`