Synnefo » ./kamaki

    addr    :  List a server nic address

    firewall:  Manage server firewall profile

        set :  Set the server firewall profile

        get :  Get the server firewall profile

        info  :  A floating IP details

    rename  :  Update a server name

.. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g., bash)

    arguments, e.g., to copy test.py object from example:dev container to

decorator called *command*. This decorator is a method of *kamaki.cli* that

adds a new command in a *CommandTree* structure. A *CommandTree* (package

*kamaki.cli.commant_tree*) is a data structure used by kamaki to manage command

namespaces.

For demonstration purposes, the following set of kamaki commands will be

implemented in this document::

There are two command groups to implement i.e., *mygrp1* and *mygrp2*,

containing two commands each (*list_all*, *list_details* and *list_all*, *info*

respectively). To avoid ambiguities, command names are prefixed with the

command group they belong to, e.g., *mygrp1_list_all* and *mygrp2_list_all*.

The underscore is used to separate command namespaces.

The first command (*mygrp1_list_all*) has the simplest possible syntax: no

parameters, no runtime arguments. The second accepts an optional runtime argument with a value. The third features an optional parameter and an optional

runtime flag argument. The last is an example of a command with an obligatory

and an optional parameter.

Examples of the expected behavior in one-command mode:

        ... (a mygrp1_list_all instance runs) ...

        ... (a mygrp2_list_all instance runs) ...

CommandTree manages a command by its namespace. Each command is stored in

a tree path, where each node is a name. A leaf is the end term of a namespace and contains a pointer to the command class to be executed.

Here is an example from the actual kamaki command structure, where the commands

*file upload*, *file list* and *file info* are represented as shown bellow::

Now, let's load the showcase example on CommandTrees::

Each command group should be stored on a different CommandTree.

For that reason, command specification modules should contain a list of CommandTree objects, named *_commands*. This mechanism allows any interface

application to load the list of commands from the *_commands* array.

The first name of the command path and a description (name, description) are needed to initializeg a CommandTree:

All commands are specified by subclasses of *kamaki.cli.commands._command_init*

These classes are called "command specifications".

The *command* decorator mines all the information needed to build a namespace

from a command specification::

Kamaki interfaces make use of the CommandTree structure. Optimizations are

        :param descedants_depth: is the depth of the tree descendants of the

A command specification developer should create a new module (python file) with

one command specification class per command. Each class should be decorated

with *command*.

*_commands*. Different CommandTree objects correspond to different command

groups.

Set command description

    class mygrp2_info():

        """get information for subject with id

        Anything from this point and bellow constitutes the long description

        Please, mind the indentation, pep8 is not forgiving.

        """

Description placeholders

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

There is possible to create an empty command, that can act as a description

placeholder. For example, the *mygrp1_list* namespace does not correspond to an

executable command, but it can have a helpful description. In that case, create

a command specification class with a command and no code:

.. code-block:: python

    @command(_mygrp1_commands)

    class mygrp1_list():

        """List mygrp1 objects.

        There are two versions: short and detailed

        """

.. warning:: A command specification class with no description is invalid and

    will cause an error.

A special argument mechanism allows the definition of run-time arguments. This

mechanism is based on argparse and is designed to simplify argument definitions

when specifying commands.

Some basic argument types are defined at the

a bad idea to extent these classes in order to achieve specialized type

checking and syntax control. Still, in most cases, the argument types of the

argument package are enough for most cases.

To declare a run-time argument on a specific command, the specification class

should contain a dict called *arguments* , where Argument objects are stored.

Each argument object is a run-time argument. Syntax checking happens at client

level, while the type checking is implemented in the Argument code (e.g.,

IntArgument checks if the value is an int).

                'Filter output to match string', ('-m', --match'))

To access run-time arguments, users can use the *_command_init* interface,

which implements *__item__* accessors to handle run-time argument values. In

other words, one may get the value of an argument with *self[<argument>]*.

The command behavior for each command class is coded in *main*. The

parameters of *main* method affect the syntax of the command. In specific::

Let's have a look at the command specification class again, and highlight the

parts that affect the command syntax:

    _commands = [_mygrp1_commands, _mygrp2_commands]

        """List all subjects

        Refers to the subject accessible by current user

        """

The above lines contain the following information:

* Namespace and name (line 8): mygrp2 list all

* Short (line 9) and long (line 10) description

* Parameters (line 15): [reg exp]

* Runtime arguments (line 13): [-l]

* Runtime arguments help (line 13): detailed list

.. tip:: It is suggested to code the main functionality in a member method

    called *_run*. This allows the separation between syntax and logic. For

    example, an external library may need to call a command without caring

    about its command line behavior.

The developer should move the file *grps.py* to *kamaki/cli/commands*, the

default place for command specifications

These lines should be contained in the kamaki configuration file for a new

command specification module to work:

.. note:: running a command specification from a different path is supported.

    To achieve this, add a *<group>_cli = </path/to/module>* line in the

    configure file under the *global* section.

::

    class mygrp1_list(_command_init):

        """List mygrp1 objects.

        There are two versions: short and detailed

        """

    @command(_mygrp1_commands)

        def _run():

        def main(self):

            self._run()

        def _run(self):

        def main(self):

        self._run()

    #The following will also create a mygrp2_list command with no description

        def _run(self, regexp):

            if self['list']:

            else:

        def main(self, regular_expression=None):

            self._run(regular_expression)

        def _run(self, grp_id, grp_name):

        def main(self, id, name=''):

            self._run(id, name) 

called *kamaki.clients* and serves as a lib.

A showcase of an application built on *kamaki.clients* is *kamaki.cli*, the

command line interface of kamaki.

the *compute*, *storage* and *image* modules are client implementations for the

OpenStack compute and OpenStack object-store APIs, respectively. The rest of the

modules implement the Synnefo extensions (i.e., *cyclades* and 

*cyclades_rest_api* extents *compute*, *pithos* and *pithos_rest_api* extent

*storage*) or novel Synnefo services (*image* for *plankton*).

There is a client for every API, therefore an external applications should

instantiate they kamaki clients they need. For example, to manage virtual

servers and stored objects / files, an application would probably need to

instantiate the CycladesClient and PithosClient respectively.

    Example 1.1: Instantiate Cyclades and Pithos clients

.. note:: *cyclades* and *pithos* clients inherit ComputeClient from *compute*

    and StorageClient from *storage*, respectively. Separate ComputeClient or

    StorageClient objects should be used only when implementing applications for

    strict OpenStack Compute or Storage services.

In OpenStack, each service (e.g., `compute`, `object-store`, etc.) has a number

of `endpoints`. These `endpoints` are actually URIs that are used by kamaki as

prefixes to form the corresponding API calls. Client applications need just

one of these these `endpoints`, namely the `publicURL`, which is also referred

to as `base_url` in kamaki client libraries.

Here are instructions for getting the base_url for a service::

is an identity server that implements the OpenStack identity API. Therefore, it

can be used to get the `base_url` values needed for initializing kamaki clients.

Kamaki simplifies this process with the astakos client library.

The ``get_service_endpoints`` method is called with the service name as an

argument. Here are the service names for the kamaki clients::

    storage.StorageClient, pithos.PithosClient      -->     object-store

    compute.ComputeClient, cyclades.CycladesClient  -->     compute

    image.ImageClient                               -->     image

    astakos.AstakosClient                           -->     identity, account

At this point we assume that we can initialize a client, so the initialization

step will be omitted in most of the examples that follow.

The next step is to take a look at the member methods of each particular client.

A detailed catalog of the member methods for all client classes can be found at

:ref:`the-client-api-ref`

are used to extract some information through the remote service APIs. The information is then printed to the standard output.

    * A run of examples 1.1 + 1.4 *

The *kamaki.clients* error class is ClientError. A ClientError is raised for

any kind of *kamaki.clients* errors (errors reported by servers, type errors in

    status      An optional error code, e.g., after a server error.

    from kamaki.clients import ClientError

        my_astakos_client.authenticate()

Two servers and a private network

'''''''''''''''''''''''''''''''''

.. code-block:: python

    #! /user/bin/python

    from kamaki.clients.astakos import AstakosClient

    from kamaki.clients.cyclades import CycladesClient

    AUTHENTICATION_URL = 'https://accounts.example.com/identity/v2.0'

    TOKEN = 'replace this with your token'

    astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)

    cyclades_endpoints = user.get_service_endpoints('compute')

    CYCLADES_URL = cyclades_endpoints['publicURL']

    FLAVOR_ID = 'put your flavor id here'

    IMAGE_ID = 'put your image id here'

    cyclades = CycladesClient(CYCLADES_URL, TOKEN)

    srv1 = cyclades.create_server('server 1', FLAVOR_ID, IMAGE_ID)

    srv2 = cyclades.create_server('server 2', FLAVOR_ID, IMAGE_ID)

    srv_state1 = cyclades.wait_server(srv1['id'])

    assert srv_state1 in ('ACTIVE'), 'Server 1 built failure'

    srv_state2 = cyclades.wait_server(srv2['id'])

    assert srv_state2 in ('ACTIVE'), 'Server 2 built failure'

    net = cyclades.create_network('My private network')

    net_state = cyclades.wait_network(net['id'])

    assert net_state in ('ACTIVE', ), 'Network built failure'

    cyclades.connect_server(srv1['id'], net['id'])

    cyclades.connect_server(srv2['id'], net['id'])

By default, kamaki clients implement REST APIs, therefore they manage HTTP

requests and responses to communicate with services.

APIs. 

To test a specific class, add the class name as an argument. e.g., for the

To test a specific method in a class, apply an extra argument, e.g., for the

command line. e.g., in the pithos package there is a test module which

To fully test a specific package, run test.py from the package location. e.g.,

By convention, testing classes have the same name as the class they test.

Methods not grouped in classes are tested by classes named after their

respective module.

For example, the *kamaki.clients.pithos.PithosClient* class is tested by the

*kamaki.clients.pithos.test.PithosClient* class, while the methods in

*kamaki.clients.utils* module are tested by *kamaki.clients.utils.test.Utils*.

After modifying or extending *kamaki.clients* method, classes, modules or

of new behavior before implementing the behavior itself. The goal is to

preserve an 1 to 1 mapping between methods and their tests.

Example: to modify *kamaki.clients.pithos.PithosRestClient.object_get*, the

*kamaki.clients.pithos.test.PithosRestClient.test.object_get* method.

To implement a new method in an existing class, developers are encouraged to

implement the corresponding unit test first. In order to do that, they should

find the testing class that is mapped to the class or module they working on.

Example: Adding **list_special** to *kamaki.clients.astakos.AstakosClient*,

requires changes to *kamaki.clients.astakos.test.AstakosClient* too, as shown

bellow:

class or module under *kamaki.clients*, should be located in a separate

Example 1: To add a NewService class that implements *kamaki.clients.Client*: 

* create a new_service package and implement the unit tests in

    *kamaki.clients.new_service.test*:

* create the file to code the package implementation:

* Create the test class and methods in *kamaki.clients.new_service.test*

* Import the test class to *kamaki.clients.test*:

.. code-block:: python

Kamaki uses the standard Python logger package to log some of its functionality.

All kamaki loggers are named or prefixed after the package they log, e.g.,

a logger at `kamaki/cli/argument/__init__.py` should be called

named `kamaki.clients.conf`. In `kamaki/clients/__init__.py` there are two

API calls::

to the log file as well as to (b) show users the HTTP requests and responses in

"verbose" or "debug" modes.

.. note:: user token and http body content are not logged by default. This can

	be switched on and off by modifing the *kamaki.client.Client.LOG_TOKEN* and

	*kamaki.client.Client.LOG_DATA* flags

of the `pithos.list_objects()` method and print these to stdout. To achieve

that goal, we should get a stream logger and deactivate it when we do not need

it anymore.

    e.g.,:

id, owner, location, checksum and dates. e.g., to publish and unpublish:

    userid=... # e.g., s0m3-u53r-1d

    container=... # e.g., pithos

    e.g.,

    default behavior depends on the remote server, e.g., for a debian image we

    inject all kinds of useful files, e.g., **lists of package sources**,

along with the custom extensions introduced by Synnefo

* Make sure the GPG public key for the Synnefo repository is added:

.. warning:: kamaki.clients unit-tests need python-mock 1.X or better. e.g.,::

Use virtualenv to setup kamaki and Synnefo services in a sandbox environment.

development team at the *Greek Research and Technology Network (GRNET)*,

developing their own python-based cloud applications.

* by the deployment team which operates GRNET ~okeanos service

To set up Kamaki for a specific Synnefo deployment, users need an

**authentication URL** and a **user token**. Users should also pick an alias to

name the cloud configuration. This can be any single word, e.g., "default",

If only one cloud is configured, it is automatically considered the default.

Lets take a look at the discarded options:

deployments. In the following, a Synnefo (or Open Stack) cloud deployment will

* tab completion for commands (if supported by the user shell)

* session history with ↑ or ↓ keys (if supported by the user shell)

    Use filtering arguments (e.g., --name-like) to manage long server lists

        e.g., spec_cmd0_cmd1 will be command spec cmd0

        :param terms: (list of str) match against paths in cmd_tree, e.g.,

    Get user information (e.g., unique account name) from token

    '  MODEL: permition in octal (e.g., 0777 or o+rwx)']

    Use filtering arguments (e.g., --name-like) to manage long server lists

    - metadata (e.g., os, superuser) and diagnostics

    .       e.g., pick 2 4-7 -3

    .   - Use negative integers to count from the end of the list, e.g.,:

    .   - Use negative integers to count from the end of the list, e.g.,:

    Some metadata can be set by user (e.g., disk-format) while others are set

    only automatically (e.g., image id). There are also some custom user

                    'e.g.,: containerlimit set 2.3GB mycontainer',

    copy, move, meta. See these commands for more information, e.g.,

    Get user information (e.g., unique account name) from token

            'commission ids to accept (e.g., --accept=11,12,13,...',

            'commission ids to reject (e.g., --reject=11,12,13,...',