code.grnet.gr Git - snf-occi/blob - docs/index.rst

   1 .. snf-occi documentation master file, created by
   2    sphinx-quickstart on Mon Mar 26 13:45:54 2012.
   3    You can adapt this file completely to your liking, but it should at least
   4    contain the root `toctree` directive.
   5
   6 snf-occi's documentation!
   7 ====================================
   8
   9 **snf-occi** implements the OCCI specification on top of synnefo’s API in order to achieve greater interoperability. This module is a translation bridge between OCCI and the synnefo endpoints.  It is designed to be as independent as possible from the rest IaaS, providing an OCCI compatibility layer.
  10
  11 **snf-occi** utilizes the API library for the components of the synnefo ecosystem provided by `kamaki <http://www.synnefo.org/docs/kamaki/latest>`_  . It is built on top of kamaki.clients lib in order to communicate with the required synnefo APIs.
  12
  13
  14 .. toctree::
  15    :maxdepth: 2
  16
  17 About OCCI
  18 ----------
  19 The current OCCI specification consists of the following three documents:
  20
  21 * `OCCI Core <http://ogf.org/documents/GFD.183.pdf>`_
  22 * `OCCI Infrastructure <http://ogf.org/documents/GFD.184.pdf>`_
  23 * `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/>`_
  26
  27 OCCI and Synnefo
  28 -----------------
  29 The OCCI implementation for Synnefo is in accordance with the OCCI Infrastructure specification, that describes common Cloud IaaS components. The correspondence between OCCI and Cyclades is as follows:
  30
  31 +-------------------------+-------------------------+
  32 |OCCI                     |Cyclades                 |
  33 +=========================+=========================+
  34 |Compute                  |Synnefo servers          |
  35 +-------------------------+-------------------------+
  36 |OS Template              |Synnefo images           |
  37 +-------------------------+-------------------------+
  38 |Resource Template        |Synnefo flavors          |
  39 +-------------------------+-------------------------+
  40 |Network                  |Synnefo networks         |
  41 +-------------------------+-------------------------+
  42 |Storage                  |NA                       |
  43 +-------------------------+-------------------------+
  44
  45
  46
  47 **Note:** Metadata info in synnefo's servers cannot be represented (clearly) using OCCI's components.
  48
  49
  50 OCCI operations
  51 ------------------
  52
  53 Below you can see the required procedures/operations for OCCI compatibility.
  54
  55 * Handling the query interface
  56    * Query interface must be found under path /-/
  57    * Retrieve all registered Kinds, Actions and Mixins
  58    * Add a Mixin definition
  59    * Remove a Mixin definition
  60
  61 * Operation on paths in the name-space
  62    * Retrieving the state of the name-space hierarchy
  63    * Retrieving all Resource instances below a path
  64    * Deletion of all Resource instances below a path
  65
  66 * Operations on Mixins and Kinds
  67    * Retrieving all Resource instances belonging to Mixin or Kind
  68    * Triggering actions to all instances of a Mixin or a Kind
  69    * Associate resource instances with a Mixin or a Kind
  70    * Full update of a Mixin collection
  71    * Dissociate resource instances from a Mixin
  72
  73 * Operations on Resource instances
  74    * Creating a resource instance
  75    * Retrieving a resource instance
  76    * Partial update of a resource instance
  77    * Full update of a resource instance
  78    * Delete a resource instance
  79    * Triggering an action on a resource instance
  80
  81 * Handling Link instances
  82    * Inline creation of a Link instance
  83    * Retrieving Resource instances with defined Links
  84    * Creating of Link Resource instance
  85
  86
  87 OCCI client/server library
  88 ---------------------------
  89
  90 **pyssf** is a collection of OCCI python modules. It aims at providing a high-level interface for the integration of OCCI to other new or existing applications.
  91
  92 **Features:**
  93
  94
  95 * It includes the implementation of a REST API service with the OCCI specifications already implemented
  96 * It only requires a custom backend and registry to interact with synnefo main components (e.g., Cyclades, Astakos. etc.)
  97
  98 snf-occi Installation
  99 ======================
 100
 101 Requirements
 102 -------------
 103
 104 First, you need to install the required dependencies which can be found here:
 105
 106 * `pyssf at pypi <https://pypi.python.org/pypi/pyssf>`_
 107 * `Kamaki repository  <https://code.grnet.gr/projects/kamaki>`_  (Detailed description for installation of kamaki can be found in this `Guide <http://www.synnefo.org/docs/kamaki/latest/installation.html>`_).
 108
 109 Moreover, some additional packages need to be installed::
 110
 111 $ apt-get install python-pip
 112 $ pip install webob
 113 $ apt-get install python-dev
 114 $ pip install eventlet
 115 $ apt-get install python-m2crypto
 116 $ apt-get install python-pastedeploy
 117 $ apt-get install libvomsapi1
 118
 119
 120 Installation
 121 -------------
 122
 123 Upon the completion of the previous steps, you can install **snf-occi** API translation server by cloning our latest source code:
 124
 125 * `snf-occi Repository <https://code.grnet.gr/git/snf-occi>`_
 126
 127 **NOTE**: Before running setup.py, you have to edit the config.py in order to setup the following information:
 128
 129 * Server related settings, e.g.,  API server port, hostname and core architecture
 130 * Endpoints for the ComputeClient and AstakosClient
 131 * Enable / Disable VOMS authentication
 132 * Paths to directories containing certificates and configuration files that enable the process for VOMS authentication
 133
 134
 135
 136 Finally, the installation of snf-occi is done with the following steps::
 137
 138 $ python setup.py build
 139 $ python setup.py install
 140
 141
 142 In case that VOMS authentication mode is disabled, then the snf-occi server can be started by typing **snf-occi**.
 143
 144
 145 Enabling VOMS authentication
 146 ============================
 147
 148
 149 VOMS Requirements
 150 ------------------
 151
 152 * Installation of **EUgridPMA** certificates, which must be located on the standard location **/etc/grid-security/certificates**:
 153
 154 ::
 155
 156 $ wget -q -O - https://dist.eugridpma.info/distribution/igtf/current/GPG-KEY-EUGridPMA-RPM-3 | sudo apt-key add -
 157 $ echo "deb http://repository.egi.eu/sw/production/cas/1/current egi-igtf core" > /etc/apt/sources.list.d/egi-cas.list (as root)
 158 $ sudo apt-get update
 159 $ sudo apt-get install ca-policy-egi-core
 160
 161 * Installation of the **fetch-crl** package:
 162
 163 ::
 164
 165 $ sudo apt-get install fetch-crl
 166 $ sudo fetch-crl
 167
 168 Moreover, a valid certificate issued by a valid CA is required for the server hosting snf-occi. The certificates of valid CAs are located in **/etc/grid-security/certificates/**. The server certificate and key file need to be located in **/etc/ssl** (if the directories with the certificate and key files differ, then the paths to these directories must be appropriately set in the **snfOCCI/config.py**).
 169
 170 ::
 171
 172 $ ls /etc/ssl/certs/server.crt
 173 $ ls /e tc/ssl/private/server.key
 174
 175
 176 Apache Installation and Configuration
 177 ------------------------------------------------
 178 To enable VOMS authentication in snf-occi, the existence of a working Apache installation is a prerequisite. The installation and configuration process is as follows:
 179
 180 * Installation of Apache WSGI with mod_ssl enabled::
 181
 182         $ sudo apt-get install apache2 libapache2-mod-wsgi
 183         $ sudo a2enmod ssl
 184         $ sudo a2enmod headers
 185
 186 * Create a user synnefo and configure Apache::
 187
 188         $ sudo adduser synnefo
 189
 190 Assuming that the snf-occi server has the FQDM nodeX.example.com, then the following configurations are required:
 191
 192
 193 * In **/etc/apache2/sites-enabled/snf_VOMS** add::
 194
 195         WSGIDaemonProcess snf_voms user=synnefo group=nogroup processes=3 threads=10
 196         Listen 8888
 197         <VirtualHost _default_:8888>
 198           LogLevel warn
 199           ErrorLog ${APACHE_LOG_DIR}/error.log
 200           CustomLog ${APACHE_LOG_DIR}/ssl_access.log combined
 201
 202           RequestHeader set X-Forwarded-Protocol "https"
 203
 204           SSLEngine on
 205           SSLCertificateFile    /etc/ssl/certs/server.crt
 206           SSLCertificateKeyFile /etc/ssl/private/server.key
 207
 208           SSLCACertificatePath /etc/grid-security/certificates
 209           SSLCARevocationPath /etc/grid-security/certificates
 210           SSLVerifyClient optional
 211           SSLVerifyDepth 20
 212           SSLProtocol all -SSLv2
 213           SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM:+LOW
 214           SSLOptions +StdEnvVars +ExportCertData
 215           WSGIScriptAlias /main /usr/lib/cgi-bin/snf_voms/main
 216           WSGIProcessGroup snf_voms
 217           WSGIPassAuthorization On
 218           WSGIScriptAlias / /usr/lib/cgi-bin/snf_voms/main
 219         </VirtualHost>
 220
 221         Listen 5000
 222         <VirtualHost _default_:5000>
 223           LogLevel warn
 224           ErrorLog ${APACHE_LOG_DIR}/error.log
 225           CustomLog ${APACHE_LOG_DIR}/ssl_access.log combined
 226
 227           SSLEngine on
 228           SSLCertificateFile    /etc/ssl/certs/server.crt
 229           SSLCertificateKeyFile /etc/ssl/private/server.key
 230
 231           SSLCACertificatePath /etc/grid-security/certificates
 232           SSLCARevocationPath /etc/grid-security/certificates
 233           SSLVerifyClient optional
 234           SSLVerifyDepth 20
 235           SSLProtocol all -SSLv2
 236           SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM:+LOW
 237           SSLOptions +StdEnvVars +ExportCertData
 238
 239           WSGIScriptAlias /main /usr/lib/cgi-bin/snf_voms/main_auth
 240           WSGIScriptAlias /main /usr/lib/cgi-bin/snf_voms/main_auth
 241           WSGIProcessGroup snf_voms
 242         </VirtualHost>
 243
 244
 245 * In **/etc/apache2/httpd.conf** add::
 246         ServerName nodeX.example.com
 247
 248
 249 * In **/etc/apache2/conf.d/wsgi-snf_voms.conf** add::
 250
 251         WSGIScriptAlias /main /var/www/cgi-bin/snf_voms/main
 252         WSGIScriptAlias /main /usr/lib/cgi-bin/snf_voms/main_auth
 253
 254         <Location "/main">
 255           SSLRequireSSL
 256           Authtype none
 257         </Location>
 258
 259 * To support VOMS authentication, snf-occi must be executed as a WSGI application. To achive this goal, the respective scripts included in the snf-occi repository need to be placed in the appropriate directories. In more detail, you have to copy the following scripts located in the **snfOCCI/httpd** directory in the appropriate directory and create the following links ::
 260
 261         $ mkdir /usr/lib/cgi-bin/snf_voms
 262         $ cp snf-occi/snfOCCI/httpd/snf_voms.py /usr/lib/cgi-bin/snf_voms/snf_voms.py
 263         $ ln /usr/lib/cgi-bin/snf_voms/snf_voms.py /usr/lib/cgi-bin/snf_voms/main
 264         $ cp snf-occi/snfOCCI/httpd/snf_voms_auth.py /usr/lib/cgi-bin/snf_voms/snf_voms_auth.py
 265         $ ln /usr/lib/cgi-bin/snf_voms/snf_voms_auth.py /usr/lib/cgi-bin/snf_voms/main_auth
 266         $ cp snf-occi/snfOCCI/snf_voms_auth-paste.ini /home/synneo/snf_voms_auth-paste.ini
 267         $ cp snf-occi/snfOCCI/snf_voms-paste.ini /home/synnefo/snf_voms-paste.ini
 268
 269
 270
 271 * In **/etc/apache2/envvars** add::
 272
 273         export OPENSSL_ALLOW_PROXY_CERTS=1
 274
 275
 276 Configure VO Membership Information
 277 ------------------------------------
 278
 279 In order to support VOMS authentication, some configuration information is required. This information is provided in the following files. For example, to allow the access for members of the fedcloud.egi.eu VO, the following configuration files need to be present in the directory **/etc/snf** :
 280
 281 * In **/etc/snf/voms.json** add::
 282
 283         {
 284           "fedcloud.egi.eu":
 285           {
 286             "tenant": "EGI_FCTF"
 287           }
 288         }
 289
 290 Moreover, the vomsdir information and the vomses file need to be created and altered respectively for each allowed VO (see also `Fedcloud-tf:CLI Environment <https://wiki.egi.eu/wiki/Fedcloud-tf:CLI_Environment>`_). For example, the respective folders and files for the **fedcloud.egi.eu** VO are created in the following two steps:
 291
 292 * Creation of the vomsdir information::
 293
 294         $ mkdir -p /etc/grid-security/vomsdir/fedcloud.egi.eu
 295         $ cat > /etc/grid-security/vomsdir/fedcloud.egi.eu/voms1.egee.cesnet.cz.lsc <<EOF
 296         /DC=org/DC=terena/DC=tcs/OU=Domain Control Validated/CN=voms1.egee.cesnet.cz
 297         /C=NL/O=TERENA/CN=TERENA eScience SSL CA
 298         EOF
 299         $ cat > /etc/grid-security/vomsdir/fedcloud.egi.eu/voms2.egee.cesnet.cz.lsc <<EOF
 300         /DC=org/DC=terena/DC=tcs/OU=Domain Control Validated /CN=voms2.grid.cesnet.cz
 301         /C=NL/O=TERENA/CN=TERENA eScience SSL CA
 302         EOF
 303
 304
 305 * Creation / Extension of the vomses file::
 306
 307         $ cat >> /etc/vomses <<EOF
 308         "fedcloud.egi.eu" "voms1.egee.cesnet.cz" "15002" "/DC=org/DC=terena/DC=tcs/OU=Domain Control Validated/CN=voms1.egee.cesnet.cz" "fedcloud.egi.eu" "24"
 309         "fedcloud.egi.eu" "voms2.grid.cesnet.cz" "15002" "/DC=org/DC=terena/DC=tcs/OU=Domain Control Validated /CN=voms2.grid.cesnet.cz" "fedcloud.egi.eu" "24"
 310         EOF
 311
 312 Upon the completion of all configuration actions, start (or restart) the Apache server:
 313
 314 $  sudo service apache2 start
 315
 316
 317 Usage Scenarios
 318 ================
 319
 320 For the examples below, we assume that the snf-occi server is running on  <snf-occi_host> (port 8888) and authentication token is $AUTH. For the HTTPS requests we are using **curl**.
 321
 322 The user must have a valid authentication token in order to interact with the snf-occi endpoint. In case that the VOMS authentication is enabled, then the user can provide his/her proxy certificate in order to obtain a valid authentication token.
 323
 324 * A user participating in a specific VO must have a valid VOMS proxy. To obtain a proxy certificate type the command (More information about the setup of a FedCloud command-line environment in order to obtain a proxy certificate can be found at `Fedcloud-tf:CLI Environment <https://wiki.egi.eu/wiki/Fedcloud-tf:CLI_Environment>`_.)::
 325
 326         $ voms-proxy-init -voms fedcloud.egi.eu -rfc
 327
 328
 329 * Retrieve an authentication token (hence referring as $AUTH) from the snf-occi server, assuming that the proxy certificate is the file $X509_USER_PROXY (e.g., /tmp/x509up_u1000) and <snf-occi_host> is the hostname of server hosting snf-occi::
 330
 331         $ curl --capath /etc/grid-security/certificates --cert $X509_USER_PROXY -d '{"auth":{"voms": true, "tenantName": "fedcloud.egi.eu"}}' -v -X GET https://<snf-occi_host>:5000/main/v2.0/tokens
 332
 333 * Retrieve all registered Kinds, Actions and Mixins:
 334
 335   ::
 336
 337         $ curl --capath /etc/grid-security/certificates -X GET https://<snf-occi_host>:8888/-/ -H 'X-Auth-Token:$AUTH'
 338
 339
 340 * List all VMs::
 341
 342         $ curl --capath /etc/grid-security/certificates -X GET https://<snf-occi_host>:8888/compute/ -H 'X-Auth-Token:$AUTH'
 343
 344
 345 * Create a new VM using the the flavor 'c1r1024d5rdb' and the image 'ubuntu_server'
 346
 347   ::
 348
 349         $ curl --capath /etc/grid-security/certificates -X POST https://<snf-occi_host>:8888/compute/ -H 'Category: compute; scheme=http://schemas.ogf.org/occi/infrastructure#;  class="kind";' -H 'X-OCCI-Attribute: occi.core.title = newVM' -H 'Category: c1r1024d5drbd; scheme=http://schemas.ogf.org/occi/resource_tpl#; ' -H 'Category: ubuntu_server; scheme=http://schemas.ogf.org/occi/os_tpl#;' -H 'X-Auth-Token:$AUTH'  -H 'Content-type: text/occi'
 350
 351
 352 * Retrieve all the details of th VM with identifier $ID::
 353
 354         $ curl --capath /etc/grid-security/certificates -X GET https://<snf-occi_host>:8888/compute/$ID -H 'X-Auth-Token: $AUTH'
 355
 356
 357
 358 * Delete the VM with identifier $ID::
 359
 360         $ curl --capath /etc/grid-security/certificates -X DELETE https://<snf-occi_host>:8888/compute/$ID -H 'X-Auth-Token: $AUTH'
 361
 362
 363 Moreover, the `rOCCI cli <https://github.com/gwdg/rOCCI-cli>`_ can be used directly from shell defining the following parameters:
 364
 365         * -- endpoint https://<snf-occi_host>:8888
 366         * --auth x509
 367         * -- voms
 368         * --user-cred $X509_USER_PROXY
 369
 370
 371 Future Directions
 372 -----------------
 373
 374 The snf-occi server is constantly evolving and being enhanced with more new features in order to support more advanced functionalities. For instance, some upcoming features are:
 375
 376 * VM Contextualization
 377 * Network Management
 378 * Data Management
 379 * VM Image Management
 380
 381
 382 Indices and tables
 383 ==================
 384
 385 * :ref:`genindex`
 386 * :ref:`search`