Synnefo

# Makefile for Sphinx documentation

#

# You can set these variables from the command line.

SPHINXOPTS    =

SPHINXBUILD   = sphinx-build

PAPER         =

BUILDDIR      = _build

# Internal variables.

PAPEROPT_a4     = -D latex_paper_size=a4

PAPEROPT_letter = -D latex_paper_size=letter

ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

# the i18n builder cannot share the environment and doctrees with the others

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext

help:

	@echo "Please use \`make <target>' where <target> is one of"

	@echo "  html       to make standalone HTML files"

	@echo "  dirhtml    to make HTML files named index.html in directories"

	@echo "  singlehtml to make a single large HTML file"

	@echo "  pickle     to make pickle files"

	@echo "  json       to make JSON files"

	@echo "  htmlhelp   to make HTML files and a HTML help project"

	@echo "  qthelp     to make HTML files and a qthelp project"

	@echo "  devhelp    to make HTML files and a Devhelp project"

	@echo "  epub       to make an epub"

	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"

	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"

	@echo "  text       to make text files"

	@echo "  man        to make manual pages"

	@echo "  texinfo    to make Texinfo files"

	@echo "  info       to make Texinfo files and run them through makeinfo"

	@echo "  gettext    to make PO message catalogs"

	@echo "  changes    to make an overview of all changed/added/deprecated items"

	@echo "  linkcheck  to check all external links for integrity"

	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"

clean:

	-rm -rf $(BUILDDIR)/*

html:

	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

	@echo

	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

dirhtml:

	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

	@echo

	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

singlehtml:

	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml

	@echo

	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

pickle:

	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

	@echo

	@echo "Build finished; now you can process the pickle files."

json:

	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json

	@echo

	@echo "Build finished; now you can process the JSON files."

htmlhelp:

	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp

	@echo

	@echo "Build finished; now you can run HTML Help Workshop with the" \

	      ".hhp project file in $(BUILDDIR)/htmlhelp."

qthelp:

	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp

	@echo

	@echo "Build finished; now you can run "qcollectiongenerator" with the" \

	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"

	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/synnefo.qhcp"

	@echo "To view the help file:"

	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/synnefo.qhc"

devhelp:

	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp

	@echo

	@echo "Build finished."

	@echo "To view the help file:"

	@echo "# mkdir -p $$HOME/.local/share/devhelp/synnefo"

	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/synnefo"

	@echo "# devhelp"

epub:

	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub

	@echo

	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

latex:

	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

	@echo

	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."

	@echo "Run \`make' in that directory to run these through (pdf)latex" \

	      "(use \`make latexpdf' here to do that automatically)."

latexpdf:

	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

	@echo "Running LaTeX files through pdflatex..."

	$(MAKE) -C $(BUILDDIR)/latex all-pdf

	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

text:

	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

	@echo

	@echo "Build finished. The text files are in $(BUILDDIR)/text."

man:

	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man

	@echo

	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

texinfo:

	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

	@echo

	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."

	@echo "Run \`make' in that directory to run these through makeinfo" \

	      "(use \`make info' here to do that automatically)."

info:

	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

	@echo "Running Texinfo files through makeinfo..."

	make -C $(BUILDDIR)/texinfo info

	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

gettext:

	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale

	@echo

	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

changes:

	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes

	@echo

	@echo "The overview file is in $(BUILDDIR)/changes."

linkcheck:

	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck

	@echo

	@echo "Link check complete; look for any errors in the above output " \

	      "or in $(BUILDDIR)/linkcheck/output.txt."

doctest:

	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest

	@echo "Testing of doctests in the sources finished, look at the " \

	      "results in $(BUILDDIR)/doctest/output.txt."

Administration

==============

This file contains notes related to administration of a working Synnefo

deployment. This document should be read *after* README.deploy, which contains

step-by-step Synnefo deployment instructions.

Database

--------

MySQL: manage.py dbshell seems to ignore the setting of 'init_command'

       in settings.DATABASES

Reconciliation mechanism

------------------------

On certain occasions, such as a Ganeti or RabbitMQ failure, the VM state in the

system's database may differ from that in the Ganeti installation. The

reconciliation process is designed to bring the system's database in sync with

what Ganeti knows about each VM, and is able to detect the following three

conditions:

 * Stale DB servers without corresponding Ganeti instances

 * Orphan Ganeti instances, without corresponding DB entries

 * Out-of-sync operstate for DB entries wrt to Ganeti instances

The reconciliation mechanism runs as a management command, e.g., as follows:

[PYTHONPATH needs to contain the parent of the synnefo Django project

directory]:

/srv/synnefo$ export PYTHONPATH=/srv:$PYTHONPATH

vkoukis@dev67:~/synnefo [reconc]$ ./manage.py reconcile --detect-all -v 2

Please see ./manage.py reconcile --help for all the details.

The administrator can also trigger reconciliation of operating state manually,

by issuing a Ganeti OP_INSTANCE_QUERY_DATA command on a Synnefo VM, using

gnt-instance info.

Logging

-------

Logging in Synnefo is using Python's logging module. The module is configured

using dictionary configuration, whose format is described here:

http://docs.python.org/release/2.7.1/library/logging.html#logging-config-dictschema

Note that this is a feature of Python 2.7 that we have backported for use in

Python 2.6.

The logging configuration dictionary is defined in settings.d/00-logging.conf

and is broken in 4 separate dictionaries:

  * LOGGING is the logging configuration used by the web app. By default all

    loggers fall back to the main 'synnefo' logger. The subloggers can be

    changed accordingly for finer logging control. e.g. To disable debug

    messages from the API set the level of 'synnefo.api' to 'INFO'.

  * DISPATCHER_LOGGING is the logging configuration of the logic/dispatcher.py

    command line tool.

  * SNFADMIN_LOGGING is the logging configuration of the snf-admin tool.

    Consider using matching configuration for snf-admin and the synnefo.admin

    logger of the web app.

Please note the following:

  * As of Synnefo v0.7, by default the Django webapp logs to syslog, the

    dispatcher logs to /var/log/synnefo/dispatcher.log and the console,

    snf-admin logs to the console.

  * Different handlers can be set to different logging levels:

    for example, everything may appear to the console, but only INFO and higher

    may actually be stored in a longer-term logfile.

Admin Tools

-----------

snf-admin is a tool used to perform various administrative tasks. It needs to

be able to access the django database, so the following should be able to import

the Django settings.

Additionally, administrative tasks can be performed via the admin web interface

located in /admin. Only users of type ADMIN can access the admin pages. To change

the type of a user to ADMIN, snf-admin can be used:

   snf-admin user modify 42 --type ADMIN

import sys, os

project = u'synnefo'

copyright = u'2012, GRNET'

version = '0.8'

release = '0.8'

html_title = 'synnefo ' + version

templates_path = ['_templates']

source_suffix = '.rst'

master_doc = 'index'

exclude_patterns = ['_build']

pygments_style = 'sphinx'

html_theme = 'nature'

html_static_path = ['_static']

htmlhelp_basename = 'synnefodoc'

intersphinx_mapping = {

        'pithon': ('http://docs.python.org/', None),

        'django': ('https://docs.djangoproject.com/en/dev/',

                   'https://docs.djangoproject.com/en/dev/_objects/')

}

SYNNEFO_DOCS_BASE_URL = 'http://docs.dev.grnet.gr/'

SYNNEFO_PROJECTS = {

    'synnefo': 'dev',

    'pithos': 'dev',

    'snf-webproject': 'dev',

    'snf-common': 'dev',

    'snf-image': 'dev',

    'snf-cyclades-app': 'dev'

}

for name, ver in SYNNEFO_PROJECTS.iteritems():

    intersphinx_mapping[name.replace("-","")] = (SYNNEFO_DOCS_BASE_URL +

                                                 '%s/%s/' % (name, ver),

                                 None)

extensions = ['sphinx.ext.intersphinx',

              'sphinx.ext.todo',

              'sphinx.ext.viewcode']

.. _cyclades-admin-guide:

===================

Administrator Guide

===================

This is the cyclades administrator guide.

It contains instructions on how to download, install and configure

the synnefo components necessary to deploy the Compute Service. It also covers

maintenance issues, e.g., upgrades of existing deployments.

The guide assumes you are familiar with all aspects of downloading, installing

and configuring packages for the Linux distribution of your choice.

Overview

--------

This guide covers the following:

Architecture

    Node types needed for a complete deployment of cyclades,

    and their roles. Throughout this guide, `node` refers to a physical machine

    in the deployment.

Installation

    The installation of services and synnefo software components for a working

    deployment of cyclades, either from source packages or the provided

    packages for Debian Squeeze.

Configuration

    Configuration of the various software components comprising an cyclades

    deployment.

Upgrades/Changelogs

    Upgrades of existing deployments of cyclades to newer versions, associated

    Changelogs.

.. _cyclades-architecture:

Architecture

------------

Nodes in an cyclades deployment belong in one of the following types.

For every type, we list the services that execute on corresponding nodes.

.. _DB_NODE:

DB

**

A node [or more than one nodes, if using an HA configuration], running a DB

engine supported by the Django ORM layer. The DB is the single source of

truth for the servicing of API requests by cyclades.

*Services:* PostgreSQL / MySQL

.. _APISERVER_NODE:

APISERVER

*********

A node running the ``api`` application contained in

:ref:`snf-cyclades-app <snf-cyclades-app>`. Any number of

:ref:`APISERVER <APISERVER_NODE>` nodes

can be used, in a load-balancing configuration, without any

special consideration. Access to a common DB ensures consistency.

*Services:* Web server, vncauthproxy

.. _QUEUE_NODE:

QUEUE

*****

A node running the RabbitMQ software, which provides AMQP functionality. More

than one :ref:`QUEUE <QUEUE_NODE>` nodes may be deployed, in an HA

configuration. Such deployments require shared storage, provided e.g., by DRBD.

*Services:* RabbitMQ [rabbitmq-server]

.. _LOGIC_NODE:

LOGIC

*****

A node running the business logic of synnefo, in Django. It dequeues

messages from QUEUE nodes, and provides the context in which business logic

functions run. It uses Django ORM to connect to the common DB and update the

state of the system, based on notifications received from the rest of the

infrastructure, over AMQP.

*Services:* the synnefo logic dispatcher, ``snf-dispatcher``

.. _GANETI_NODES:

.. _GANETI_MASTER:

.. _GANETI_NODE:

GANETI-MASTER and GANETI-NODE

*****************************

A single GANETI-MASTER and a large number of GANETI-NODEs constitute the

Ganeti backend for synnefo, which undertakes all VM management functions.

Any APISERVER can issue commands to the GANETI-MASTER, over RAPI, to effect

changes in the state of the VMs. The GANETI-MASTER runs the Ganeti request

queue.

*Services:*

    * only on :ref:`GANETI-MASTER <GANETI_MASTER>`:

        * the synnefo Ganeti monitoring daemon, ``snf-ganeti-eventd``

        * the synnefo Ganeti hook, ``ganeti/snf-ganeti-hook.py``.

    * on every :ref:`GANETI-NODE <GANETI_NODE>`:

        * a deployment-specific KVM ifup script

        * properly configured :ref:`NFDHCPD <cyclades-nfdhcpd-setup>`

.. _WEBAPP_NODE:

Installation

------------

Installation of cyclades is a two step process:

1. install the external services (prerequisites) on which cyclades depends

2. install the synnefo software components associated with cyclades

Prerequisites

*************

.. _cyclades-install-ganeti:

Ganeti installation

```````````````````

Synnefo requires a working Ganeti installation at the backend. Installation

of Ganeti is not covered by this document, please refer to

`ganeti documentation <http://docs.ganeti.org/ganeti/current/html>`_ for all the 

gory details. A successful Ganeti installation concludes with a working 

:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs <GANETI_NODES>`.

.. _cyclades-install-db:

Database

````````

Database installation is done as part of the

:ref:`snf-webproject <snf-webproject>` component.

.. _cyclades-install-rabbitmq:

RabbitMQ 

````````

RabbitMQ is used as a generic message broker for cyclades. It should be

installed on two seperate :ref:`QUEUE <QUEUE_NODE>` nodes in a high availability

configuration as described here:

    http://www.rabbitmq.com/pacemaker.html

After installation, create a user and set its permissions:

.. code-block:: console

    $ rabbitmqctl add_user <username> <password>

    $ rabbitmqctl set_permissions -p / <username>  "^.*" ".*" ".*"

The values set for the user and password must be mirrored in the

``RABBIT_*`` variables in your settings, as managed by

:ref:`snf-common <snf-common>`.

.. todo:: Document an active-active configuration based on the latest version

   of RabbitMQ.

.. _cyclades-install-vncauthproxy:

vncauthproxy

````````````

To support OOB console access to the VMs over VNC, the vncauthproxy

daemon must be running on every :ref:`APISERVER <APISERVER_NODE>` node.

.. note:: The Debian package for vncauthproxy undertakes all configuration

   automatically.

Download and install the latest vncauthproxy from its own repository,

at `https://code.grnet.gr/git/vncauthproxy`, or a specific commit:

.. code-block:: console

    $ bin/pip install -e git+https://code.grnet.gr/git/vncauthproxy@INSERT_COMMIT_HERE#egg=vncauthproxy

Create ``/var/log/vncauthproxy`` and set its permissions appropriately.

Alternatively, build and install Debian packages.

.. code-block:: console

    $ git checkout debian

    $ dpkg-buildpackage -b -uc -us

    # dpkg -i ../vncauthproxy_1.0-1_all.deb

.. warning::

    **Failure to build the package on the Mac.**

    ``libevent``, a requirement for gevent which in turn is a requirement for

    vncauthproxy is not included in `MacOSX` by default and installing it with

    MacPorts does not lead to a version that can be found by the gevent

    build process. A quick workaround is to execute the following commands::

        $ cd $SYNNEFO

        $ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy

        <the above fails>

        $ cd build/gevent

        $ sudo python setup.py -I/opt/local/include -L/opt/local/lib build

        $ cd $SYNNEFO

        $ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy

.. todo:: Mention vncauthproxy bug, snf-vncauthproxy, inability to install using pip

.. todo:: kpap: fix installation commands

.. _cyclades-install-nfdhcpd:

NFDHCPD

```````

Setup Synnefo-specific networking on the Ganeti backend.

This part is deployment-specific and must be customized based on the

specific needs of the system administrators.

A reference installation will use a Synnefo-specific KVM ifup script,

NFDHCPD and pre-provisioned Linux bridges to support public and private

network functionality. For this:

Grab NFDHCPD from its own repository (https://code.grnet.gr/git/nfdhcpd),

install it, modify ``/etc/nfdhcpd/nfdhcpd.conf`` to reflect your network

configuration.

Install a custom KVM ifup script for use by Ganeti, as

``/etc/ganeti/kvm-vif-bridge``, on GANETI-NODEs. A sample implementation is

provided under ``/contrib/ganeti-hooks``. Set ``NFDHCPD_STATE_DIR`` to point

to NFDHCPD's state directory, usually ``/var/lib/nfdhcpd``.

.. todo:: soc: document NFDHCPD installation, settle on KVM ifup script

.. _cyclades-install-snfimage:

snf-image

`````````

Install the :ref:`snf-image <snf-image>` Ganeti OS provider for image

deployment.

For :ref:`cyclades <cyclades>` to be able to launch VMs from specified

Images, you need the snf-image OS Provider installed on *all* Ganeti nodes.

Please see `https://code.grnet.gr/projects/snf-image/wiki`_

for installation instructions and documentation on the design

and implementation of snf-image.

Please see `https://code.grnet.gr/projects/snf-image/files`

for the latest packages.

Images should be stored in ``extdump``, or ``diskdump`` format in a directory

of your choice, configurable as ``IMAGE_DIR`` in 

:file:`/etc/default/snf-image`.

synnefo components

******************

You need to install the appropriate synnefo software components on each node,

depending on its type, see :ref:`Architecture <cyclades-architecture>`.

Most synnefo components have dependencies on additional Python packages.

The dependencies are described inside each package, and are setup

automatically when installing using :command:`pip`, or when installing 

using your system's package manager.

Please see the page of each synnefo software component for specific

installation instructions, where applicable.

Install the following synnefo components:

Nodes of type :ref:`APISERVER <APISERVER_NODE>`

    Components

    :ref:`snf-common <snf-common>`,

    :ref:`snf-webproject <snf-webproject>`,

    :ref:`snf-cyclades-app <snf-cyclades-app>`

Nodes of type :ref:`GANETI-MASTER <GANETI_MASTER>` and :ref:`GANETI-NODE <GANETI_NODE>`

    Components

    :ref:`snf-common <snf-common>`,

    :ref:`snf-cyclades-gtools <snf-cyclades-gtools>`

Nodes of type :ref:`LOGIC <LOGIC_NODE>`

    Components

    :ref:`snf-common <snf-common>`,

    :ref:`snf-webproject <snf-webproject>`,

    :ref:`snf-cyclades-app <snf-cyclades-app>`.

Configuration

-------------

This section targets the configuration of the prerequisites for cyclades,

and the configuration of the associated synnefo software components.

synnefo components

******************

cyclades uses :ref:`snf-common <snf-common>` for settings.

Please refer to the configuration sections of

:ref:`snf-webproject <snf-webproject>`,

:ref:`snf-cyclades-app <snf-cyclades-app>`,

:ref:`snf-cyclades-gtools <snf-cyclades-gtools>` for more

information on their configuration.

Ganeti

``````

Set ``GANETI_NODES``, ``GANETI_MASTER_IP``, ``GANETI_CLUSTER_INFO`` based on

your :ref:`Ganeti installation <cyclades-install-ganeti>` and change the

`BACKEND_PREFIX_ID`` setting, using an custom ``PREFIX_ID``.

Database

````````

Once all components are installed and configured,

initialize the Django DB:

.. code-block:: console

   $ snf-manage syncdb

   $ snf-manage migrate

and load fixtures ``{users, flavors, images}``, 

which make the API usable by end users by defining a sample set of users, 

hardware configurations (flavors) and OS images:

.. code-block:: console

   $ snf-manage loaddata /path/to/users.json

   $ snf-manage loaddata flavors

   $ snf-manage loaddata images

.. warning:: 

    Be sure to load a custom users.json and select a unique token 

    for each of the initial and any other users defined in this file. 

    **DO NOT LEAVE THE SAMPLE AUTHENTICATION TOKENS** enabled in deployed

    configurations.

sample users.json file:

.. literalinclude:: ../../synnefo/db/fixtures/users.json

`download <../_static/users.json>`_

RabbitMQ

````````

Change ``RABBIT_*`` settings to match your :ref:`RabbitMQ setup

<cyclades-install-rabbitmq>`.

.. include:: ../../Changelog

Administration Tools User's Guide

=================================

Configure kamaki

----------------

To upload, register or modify an image you will need the **kamaki** tool.

Before proceeding make sure that it is configured properly. Verify that

*image_url*, *storage_url*, and *token* are set as needed:

.. code-block:: console

  kamaki config list

To chage a setting use ``kamaki config set``:

.. code-block:: console

  kamaki config set image_url https://cyclades.example.com/plankton

  kamaki config set storage_url https://pithos.example.com/v1

  kamaki config set token ...

Upload an image

---------------

As a shortcut, you can configure a default account and container that will be

used by the ``kamaki store`` commands:

.. code-block:: console

  kamaki config set storage_account images@example.com

  kamaki config set storage_container images

If the container does not exist, you will have to create it before uploading

any images:

.. code-block:: console

  kamaki store create images

You are now ready to upload an image. You can upload it with a Pithos client

or use kamaki directly:

.. code-block:: console

  kamaki store upload ubuntu.iso

You can use any Pithos client to verify that the image was uploaded correctly.

The full Pithos URL for the previous example will be

``pithos://images@example.com/images/ubuntu.iso``.

Register the image

------------------

To register an image you will need to use the full Pithos URL. To register as

a public image the one from the previous example use:

.. code-block:: console

  kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso --public

The ``--public`` flag is important, if missing the registered image will not

be listed by ``kamaki glance list``.

Use ``kamaki glance register`` with no arguments to see a list of available

options. A more complete example would be the following:

.. code-block:: console

  kamaki glance register Ubuntu pithos://images@example.com/images/ubuntu.iso \

      --public --disk-format diskdump --property kernel=3.1.2

To verify that the image was registered successfully use:

.. code-block:: console

  kamaki glance list -l

API Guide

*********

.. todo:: Document the relation of the API to the OpenStack API v1.1.

This is the guide to the REST API of the synnefo Compute Service.

It is meant for users wishing to make calls to the REST API directly.

The :ref:`kamaki <http://docs.dev.grnet.gr/kamaki>` command-line client

and associated python library can be used instead of making direct calls to

:ref:`cyclades <cyclades>`.

Overview

========

* It is not defined if requests for invalid URLs should return 404 or a Fault.

  We return a BadRequest Fault.

* It is not defined if requests with a wrong HTTP method should return 405 or a

  Fault. We return a BadRequest Fault.

General API Information

=======================

Authentication

--------------

* Authentication support is missing.

Request/Response Types

----------------------

* We only support JSON Requests and JSON/XML Responses. XML Requests are not

  supported for now.

Content Compression

-------------------

* Optional content compression support is missing.

Persistent Connections

----------------------

* Deployment note: "To prevent abuse, HTTP sessions have a timeout of 20

  seconds before being closed."

Links and References

--------------------

* Full URI references support is missing.

* Self and bookmark links support is missing.

Paginated Collections

---------------------

* Pagination support is missing.

Caching

-------

* We do not return cached responses.

Limits

------

 * Limits support is missing.

Efficient Polling with the Changes-Since Parameter

--------------------------------------------------

* We only support the changes-since parameter in **List Servers** and **List

  Images**.

* We assume that garbage collection of deleted servers will only affect servers

  deleted ``POLL_TIME`` seconds in the past or earlier. Else we lose the

  information of a server getting deleted.

* Images do not support a deleted state, so we can not track deletions.

Versions

--------

* Version MIME type support is missing.

* Versionless requests are not supported.

* We hardcode the ``updated`` field in versions list

* Deployment note: The Atom metadata need to be fixed

Extensions

----------

* Extensions support is missing.

Faults

------

API Operations

==============

Servers

-------

* ``hostId`` is always empty.

* ``affinityId`` is not returned.

* ``progress`` is always returned.

* ``self`` and ``bookmark`` atom links are not returned.

* **Get Server Details** will also return servers with a DELETED state.

* **Create Server** ignores ``personality`` of requests.

* **Create Server** ignores the disk size of the flavor.

* **Create Server** hardcodes the OS.

* **Create Server** does not support setting the password in the request.

List Servers

............

* **List Servers** returns just ``id`` and ``name`` if details are not

  requested.

* **List Servers** can return 304 (even though not explicitly stated) when

  ``changes-since`` is given.

**Example List Servers: JSON**

.. code-block:: javascript

  {

      'servers':

          {'values': [

              {

                  'addresses': {'values': [

                          {

                              'id': 'public',

                              'mac': 'aa:00:00:49:2e:7e',

                              'name': 'public',

                              'values': [ {'addr': '192.168.32.6', 'version': 4} ]

                          }

                  ]},

                  'created': '2011-04-19T10:18:52.085737+00:00',

                  'flavorRef': 1,

                  'hostId': '',

                  'id': 1,

                  'imageRef': 3,

                  'metadata': {'values': {'foo': 'bar'}},

                  'name': 'My Server',

                  'status': 'ACTIVE',

                  'updated': u'2011-05-29T14:07:07.037602+00:00'

              },

              {

                  'addresses': {'values': [

                          {

                              'id': 'public',

                              'mac': 'aa:00:00:91:2f:df',

                              'name': 'public',

                              'values': [ {'addr': '192.168.32.7', 'version': 4} ]

                          },

                          {

                              'id': '2',

                              'mac': 'aa:00:00:c3:69:6f',

                              'name': 'private'

                          },

                  ]},

                  'created': '2011-05-02T20:51:08.527759+00:00',

                  'flavorRef': 1,

                  'hostId': '',

                  'id': 2,

                  'imageRef': 3,

                  'name': 'Other Server',

                  'progress': 0,

                  'status': 'ACTIVE',

                  'updated': '2011-05-29T14:59:11.267087+00:00'

              }

          ]

      }

  }

Get Server Stats

................

**GET** /servers/*id*/stats

**Normal Response Code**: 200

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)

This operation returns URLs to graphs showing CPU and Network statistics. A

``refresh`` attribute is returned as well that is the recommended refresh rate

of the stats for the clients.

This operation does not require a request body.

**Example Get Server Stats Response: JSON**:

.. code-block:: javascript

  {

      "stats": {

          "serverRef": 1,

          "refresh": 60,

          "cpuBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png",

          "cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png",

          "netBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png",

          "netTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png"

      }

  }

**Example Get Network Details Response: XML**:

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <stats xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"

      serverRef="1"

      refresh="60"

      cpuBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png"

      cpuTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png"

      netBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png"

      netTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png">

  </stats>

Server Addresses

----------------

Server Actions

--------------

* **Change Password** is not supported.

* **Rebuild Server** is not supported.

* **Resize Server** is not supported.

* **Confirm Resized Server** is not supported.

* **Revert Resized Server** is not supported.

We have have extended the API with the following commands:

Start Server

............

**Normal Response Code**: 202

**Error Response Codes**: serviceUnavailable (503), itemNotFound (404)

The start function transitions a server from an ACTIVE to a STOPPED state.

**Example Action Start: JSON**:

.. code-block:: javascript

  {

      "start": {}

  }

This operation does not return a response body.

Shutdown Server

...............

**Normal Response Code**: 202

**Error Response Codes**: serviceUnavailable (503), itemNotFound (404)

The start function transitions a server from a STOPPED to an ACTIVE state.

**Example Action Shutdown: JSON**:

.. code-block:: javascript

  {

      "shutdown": {}

  }

This operation does not return a response body.

Get Server Console

**Normal Response Code**: 200

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), buildInProgress (409), overLimit (413)

The console function arranges for an OOB console of the specified type. Only consoles of type "vnc" are supported for now.

It uses a running instance of vncauthproxy to setup proper VNC forwarding with a random password, then returns the necessary VNC connection info to the caller.

**Example Action Console: JSON**:

.. code-block:: javascript

  {

      "console": {

          "type": "vnc"

      }

  }

**Example Action Console Response: JSON**:

.. code-block:: javascript

  {

      "console": {

          "type": "vnc",

          "host": "vm42.ocean.grnet.gr",

          "port": 1234,

          "password": "IN9RNmaV"

      }

  }

**Example Action Console Response: XML**:

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <console xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"

      type="vnc"

      host="vm42.ocean.grnet.gr"

      port="1234"

      password="IN9RNmaV">

  </console>

Set Firewall Profile

....................

**Normal Response Code**: 202

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),

buildInProgress (409), overLimit (413)

The firewallProfile function sets a firewall profile for the public interface

of a server.

The allowed profiles are: **ENABLED**, **DISABLED** and **PROTECTED**.

**Example Action firewallProfile: JSON**:

.. code-block:: javascript

  {

      "firewallProfile": {

          "profile": "ENABLED"

      }

  }

This operation does not return a response body.

Flavors

-------

* ``self`` and ``bookmark`` atom links are not returned.

* **List Flavors** returns just ``id`` and ``name`` if details is not requested.

Images

------

* ``progress`` is always returned.

* ``self`` and ``bookmark`` atom links are not returned.

* **List Images** returns just ``id`` and ``name`` if details are not requested.

* **List Images** can return 304 (even though not explicitly stated) when

  ``changes-since`` is given. 

* **List Images** does not return deleted images when ``changes-since`` is given.

Metadata

--------

* **Update Server Metadata** and **Update Image Metadata** will only return the

  metadata that were updated (some could have been skipped).

Networks

--------

This is an extension to the OpenStack API.

A Server can connect to one or more networks identified by a numeric id. Each

user has access only to networks created by himself. When a network is deleted,

all connections to it are deleted. Likewise, when a server is deleted, all

connections of that server are deleted.

There is a special **public** network with the id *public* that can be accessed

at */networks/public*. All servers are connected to **public** by default and

this network can not be deleted or modified in any way.

List Networks

.............

**GET** /networks

**GET** /networks/detail

**Normal Response Codes**: 200, 203

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), overLimit (413)

This operation provides a list of private networks associated with your account.

This operation does not require a request body.

**Example Networks List Response: JSON (detail)**:

.. code-block:: javascript

  {

      "networks": {

          "values": [

              {

                  "id": "public",

                  "name": "public",

                  "created": "2011-04-20T15:31:08.199640+00:00",

                  "updated": "2011-05-06T12:47:05.582679+00:00",

                  "servers": {

                      "values": [1, 2, 3]

                  }

              },

              {

                  "id": 2,

                  "name": "private",

                  "created": "2011-04-20T14:32:08.199640+00:00",

                  "updated": "2011-05-06T11:40:05.582679+00:00",

                  "servers": {

                      "values": [1]

                  }

              }

          ]

      }

  }

**Example Networks List Response: XML (detail)**:

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <networks xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom">

    <network id="public" name="public" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00">

      <servers>

        <server id="1"></server>

        <server id="2"></server>

        <server id="3"></server>

      </servers>

    </network>

    <network id="2" name="private" updated="2011-05-06T12:47:05.582679+00:00" created="2011-04-20T15:31:33.911299+00:00">

      <servers>

        <server id="1"></server>

      </servers>

    </network>

  </networks>

Create Network

..............

**POST** /networks

**Normal Response Code**: 202

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badMediaType(415), badRequest (400), overLimit (413)

This operation asynchronously provisions a new private network.

**Example Create Network Request: JSON**:

.. code-block:: javascript

  {

      "network": {

          "name": "private_net",

      }

  }

**Example Create Network Response: JSON**:

.. code-block:: javascript

  {

      "network": {

          "id": 3,

          "name": "private_net",

          "created": "2011-04-20T15:31:08.199640+00:00",

          "servers": {

              "values": []

          }

      }

  }

**Example Create Network Response: XML**:

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"

   id="2" name="foob" created="2011-04-20T15:31:08.199640+00:00">

    <servers>

    </servers>

  </network>

Get Network Details

...................

**GET** /networks/*id*

**Normal Response Codes**: 200, 203

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)

This operation returns the details of a specific network by its id.

This operation does not require a request body.

**Example Get Network Details Response: JSON**:

.. code-block:: javascript

  {

      "network": {

          "id": 3,

          "name": "private_net",

          "servers": {

              "values": [1, 7]

          }

      }

  }

**Example Get Network Details Response: XML**::

  <?xml version="1.0" encoding="UTF-8"?>

  <network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"

   id="2" name="foob" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00">

    <servers>

      <server id="1"></server>

      <server id="7"></server>

    </servers>

  </network>

Update Network Name

...................

**PUT** /networks/*id*

**Normal Response Code**: 204

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),

overLimit (413) 

This operation changes the name of the network in the Compute system.

**Example Update Network Name Request: JSON**::

.. code-block:: javascript

  {

      "network": {

          "name": "new_name"

      }

  }

This operation does not contain a response body.

Delete Network

..............

**DELETE** /networks/*id*

**Normal Response Code**: 204

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), itemNotFound (404), unauthorized (401), overLimit (413) 

This operation deletes a network from the system.

This operation does not require a request or a response body.

Network Actions

---------------

Add Server

..........

**POST** /networks/*id*/action

**Normal Response Code**: 202

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),

overLimit (413)

This operation adds a server to the specified network.

**Example Action Add: JSON**:

.. code-block:: javascript

  {

      "add" : {

          "serverRef" : 42

      }

  }

This operation does not contain a response body.

Remove Server

.............

**POST** /networks/*id*/action

**Normal Response Code**: 202

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),

overLimit (413)

This operation removes a server from the specified network.

**Example Action Remove: JSON**:

.. code-block:: javascript

  {

      "remove" : {

          "serverRef" : 42

      }

  }

This operation does not contain a response body.

.. _cyclades-developer-guide:

===============

Developer Guide

===============

This is the cyclades developer guide.

It is intended for developers, wishing to implement new functionality

inside :ref:`cyclades <cyclades>`.

It assumes thorough familiarity with the :ref:`cyclades-admin-guide`.

Building a dev environment

--------------------------

virtualenv

**********

The easiest method to deploy a development environment is using

:command:`virtualenv`. Alternatively, you can use your system's package manager

to install any dependencies of synnefo components (e.g. Macports has them all).

   .. code-block:: console

      $ virtualenv ~/synnefo-env

      $ source ~/synnefo-env/bin/activate

      (synnefo-env)$ 

Virtualenv creates an isolated python environment to the path you pass as the

first argument of the command. That means that all packages you install using

:command:`pip` or :command:`easy_install` will be placed in

``ENV/lib/pythonX.X/site-packages`` and their console scripts in ``ENV/bin/``.

This allows you to develop against multiple versions of packages that your

software depends on without messing with system python packages that may be

needed in specific versions for other software you have installed on your

system.

* It is also recommended to install development helpers:

  .. code-block:: console

     (synnefo-env)$ pip install django_extensions fabric>=1.3

* Create a custom settings directory for :ref:`snf-common <snf-common>` and set

  the ``SYNNEFO_SETTINGS_DIR`` environment variable to use development-specific

  file:`*.conf` files inside this directory.

  (synnefo-env)$ mkdir ~/synnefo-settings-dir

  (synnefo-env)$ export SYNNEFO_SETTINGS_DIR=~/synnefo-settings-dir

  Insert your custom settings in a file such as :file:`$SYNNEFO_SETTINGS_DIR/99-local.conf`:

  .. code-block:: python

        # uncomment this if have django-extensions installed (pip install django_extensions)

        #INSTALLED_APPS = list(INSTALLED_APPS) + ['django_extensions']

        DEV_PATH = os.path.abspath(os.path.dirname(__file__))

        DATABASES['default']['NAME'] = os.path.join(DEV_PATH, "synnefo.sqlite")

        # development rabitmq configuration

        RABBIT_HOST = "<RabbitMQ_host>"

        RABBIT_USERNAME = "<RabbitMQ_username>"

        RABBIT_PASSWORD = "<RabbitMQ_password>"

        RABBIT_VHOST = "/"

        # development ganeti settings

        GANETI_MASTER_IP = "<Ganeti_master_IP>"

        GANETI_CLUSTER_INFO = (GANETI_MASTER_IP, 5080, "<username>", "<password>")

        GANETI_CREATEINSTANCE_KWARGS['disk_template'] = 'plain'

        # This prefix gets used when determining the instance names

        # of Synnefo VMs at the Ganeti backend.

        # The dash must always appear in the name!

        BACKEND_PREFIX_ID = "<your_commit_name>-"

        IGNORE_FLAVOR_DISK_SIZES = True

        # do not actually send emails

        # save them as files in /tmp/synnefo-mails

        EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'

        EMAIL_FILE_PATH = '/tmp/synnefo-mails'

        # for UI developers

        UI_HANDLE_WINDOW_EXCEPTIONS = False

        # allow login using /?test url