Synnefo

project = u'snf-asterias-app'

    'snf-asterias-app': 'dev'

.. _snf-asterias-app:

Component snf-asterias-app

synnefo component :ref:`snf-asterias-app <snf-asterias-app>` defines

the web application for asterias. It includes the following:

:ref:`asterias <snf-asterias>`. It must run on :ref:`LOGIC <LOGIC_NODE>` nodes.

for :ref:`asterias <snf-asterias>`.

or request a specific version as ``snf-asterias-app==x.y.z``.

   $ pip install snf-asterias-app -f https://docs.dev.grnet.gr/pypi

On Debian Squeeze, install the ``snf-asterias-app`` Debian package.

on how to serve :ref:`snf-asterias-app <snf-asterias-app>` as part of a

Component :ref:`snf-asterias-app <snf-asterias-app>` requires the following

    'snf-asterias-app': 'dev'

.. _asterias-admin-guide:

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

Administrator Guide

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

This is the asterias 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 asterias,

    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 asterias, either from source packages or the provided

    packages for Debian Squeeze.

Configuration

    Configuration of the various software components comprising an asterias

    deployment.

Upgrades/Changelogs

    Upgrades of existing deployments of asterias to newer versions, associated

    Changelogs.

.. _asterias-architecture:

Architecture

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

Nodes in an asterias 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 asterias.

*Services:* PostgreSQL / MySQL

.. _APISERVER_NODE:

APISERVER

*********

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

:ref:`snf-asterias-app <snf-asterias-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 <asterias-nfdhcpd-setup>`

.. _WEBAPP_NODE:

Installation

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

Installation of asterias is a two step process:

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

2. install the synnefo software components associated with asterias

Prerequisites

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

.. _asterias-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>`.

.. _asterias-install-db:

Database

````````

Database installation is done as part of the

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

.. _asterias-install-rabbitmq:

RabbitMQ 

````````

RabbitMQ is used as a generic message broker for asterias. 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.

.. _asterias-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

.. _asterias-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

.. _asterias-install-snfimage:

snf-image

`````````

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

deployment.

For :ref:`asterias <asterias>` 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 <asterias-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-asterias-app <snf-asterias-app>`

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

    Components

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

    :ref:`snf-asterias-ganeti-tools <snf-asterias-ganeti-tools>`

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

    Components

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

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

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

Configuration

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

This section targets the configuration of the prerequisites for asterias,

and the configuration of the associated synnefo software components.

synnefo components

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

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

Please refer to the configuration sections of

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

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

:ref:`snf-asterias-ganeti-tools <snf-asterias-ganeti-tools>` for more

information on their configuration.

Ganeti

``````

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

your :ref:`Ganeti installation <asterias-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

<asterias-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*, *storage_account*, *storage_container* and

*token* are set as needed::

  kamaki config list

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

  kamaki config set storage_account okeanos

  kamaki config set storage_container images

  kamaki config set token ...

Upload an image

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

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

or use kamaki directly::

  kamaki store upload ubuntu.iso

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

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::

  kamaki glance register Ubuntu pithos://okeanos/images/ubuntu.iso --public

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

options. A more complete example would be the following::

  kamaki glance register Ubuntu pithos://okeanos/images/ubuntu.iso --public \

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

To verify that the image was registered successfully use::

  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:`asterias <asterias>`.

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.

.. _asterias-developer-guide:

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

Developer Guide

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

This is the asterias developer guide.

It is intended for developers, wishing to implement new functionality

inside :ref:`asterias <asterias>`.

It assumes thorough familiarity with the :ref:`asterias-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

        BYPASS_AUTHENTICATION = True 

synnefo source

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

* Clone the repository of the synnefo software components you wish

  to work on, e.g.:

   .. code-block:: console

     (synnefo-env)$ git clone https://code.grnet.gr/git/synnefo synnefo

     (synnefo-env)$ git clone https://code.grnet.gr/git/pithos pithos

* Install the software components you wish to work on inside the

  virtualenv, in development mode:

   .. code-block:: console

      (synnefo-env)$ cd snf-asterias-app

      (synnefo-env)$ python setup.py develop -N

* Initialize database:

   .. code-block:: console

      (synnefo-env)$ snf-manage syndb

      (synnefo-env)$ snf-manage migrate

      (synnefo-env)$ snf-manage loaddata users flavors images

Development tips

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

* Running a development web server:

  .. code-block:: console

     (synnefo-env)$ snf-manage runserver

  or, if you have the ``django_extensions`` and ``werkzeug`` packages installed:

  .. code-block:: console

     (synnefo-env)$ snf-manage runserver_plus

* Opening a python console with the synnefo environment initialized:

  .. code-block:: console

     (synnefo-env)$ snf-manage shell

  or, with the django_extensions package installed:

  .. code-block:: console

     (synnefo-env)$ snf-manage shell_plus

South Database Migrations

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

.. _asterias-dev-initialmigration:

Initial Migration

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

To initialize south migrations in your database the following commands must be

executed:

.. code-block:: console

   $ snf-manage syncdb --all      # Create / update the database with the south tables

   $ snf-manage migrate --fake    # Perform migration in the database

Note that ``--all`` and ``--fake`` arguments are only needed when you are

initializing your database. If you want to migrate a previously create databse

to the latest db scheme just run the same commands without those arguments.

If you are trying to migrate a database that already contains the changes that

applied from a specific migration script, ``south`` will probably notify you for

inconsistent db scheme, a workaround for that issue is to use ``--fake`` option

for a specific migration.

For example:

.. code-block:: console

   $ snf-manage migrate db 0001 --fake

To be sure that all migrations are applied use:

.. code-block:: console

   $ snf-manage migrate db --list

All starred migrations are applied.

Schema migrations

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

Do not use the syncdb management command. It can only be used the first time

and/or if you drop the database and must recreate it from scratch. See

:ref:`asterias-dev-initialmigration`.

Every time you make changes to the database and data migration is not required

(WARNING: always perform this with extreme care):

.. code-block:: console

   $ snf-manage schemamigration db --auto

The above will create the migration script. Now this must be applied to the live

database:

.. code-block:: console

   $ snf-manage migrate db

Consider this example (adding a field to the ``SynnefoUser`` model):

.. code-block:: console

   $ ./bin/python manage.py schemamigration db --auto

   + Added field new_south_test_field on db.SynnefoUser

   Created 0002_auto__add_field_synnefouser_new_south_test_field.py.

You can now apply this migration with:

.. code-block:: console

   $ ./manage.py migrate db

   Running migrations for db:

   - Migrating forwards to 0002_auto__add_field_synnefouser_new_south_test_field.

   > db:0002_auto__add_field_synnefouser_new_south_test_field

   - Loading initial data for db.

   Installing json fixture 'initial_data' from '/home/bkarak/devel/synnefo/../synnefo/db/fixtures'.

   Installed 1 object(s) from 1 fixture(s)

South needs some extra definitions to the model to preserve and migrate the

existing data, for example, if we add a field in a model, we should declare its

default value. If not, South will propably fail, after indicating the error:

.. code-block:: console

   $ ./bin/python manage.py schemamigration db --auto

   ? The field 'SynnefoUser.new_south_field_2' does not have a default specified, yet is NOT NULL.

   ? Since you are adding or removing this field, you MUST specify a default

   ? value to use for existing rows. Would you like to:

   ?  1. Quit now, and add a default to the field in models.py

   ?  2. Specify a one-off value to use for existing columns now

   ? Please select a choice: 1

Data migrations

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

To do data migration as well, for example rename a field, use the

``datamigration`` management command.

In contrast with ``schemamigration``, to perform complex data migration, we

must write the script manually. The process is the following:

1. Introduce the changes in the code and fixtures (initial data).

2. Execute:

   .. code-block:: console

      $ snf-manage datamigration <migration_name_here>

   For example:

   .. code-block:: console

      $ ./bin/python manage.py datamigration db rename_credit_wallet

      Created 0003_rename_credit_wallet.py.

3. Edit the generated script. It contains two methods, ``forwards`` and

   ``backwards``.

   For database operations (column additions, alter tables etc), use the

   South database API (http://south.aeracode.org/docs/databaseapi.html).

   To access the data, use the database reference (``orm``) provided as

   parameter in ``forwards``, ``backwards`` method declarations in the

   migration script. For example:

   .. code-block:: python

      class Migration(DataMigration):

      def forwards(self, orm):

          orm.SynnefoUser.objects.all()

4. To migrate the database to the latest version, run:

   .. code-block:: console     

      $ snf-manage migrate db

   To see which migrations are applied:

   .. code-block:: console

      $ snf-manage migrate db --list

      db

        (*) 0001_initial

        (*) 0002_auto__add_field_synnefouser_new_south_test_field

        (*) 0003_rename_credit_wallet

.. seealso::

    More information and more thorough examples can be found in the South web site,

    http://south.aeracode.org/

Test coverage

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

.. warning:: This section may be out of date.

In order to get code coverage reports you need to install django-test-coverage

.. code-block:: console