Synnefo » ./kamaki

Creating applications with the clients API

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

Please do!

The clients API

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

The clients API is based on:

It contains the following modules:

^^^^^^^

^^^^^^^^

^^^^^^^

^^^^^^

^^^^^^^^^^^^^^^

^^^^^

^^^^^^^

^^^^^

./kamaki is open source and released under a 2-clause BSD License.

This guide describes the standard installation process for kamaki, with the aspiration of covering as much cases as possible. Although kamaki was initially targeted to advanced Linux/Unix-like users, it should be quite straightforward to install and have it up and running in most popular platforms.

Here, at the *Greek Research and Technology Network*, we have been developing an IaaS cloud management software called **synnefo** (or **+nefo**) that is accessed and managed via an extended OpenStack Compute API v1.1. Synnefo has been deployed in many environments to cover multiple needs. For example, the `~okeanos <http://okeanos.grnet.gr>`_ IaaS service, running in our data centers, is used to offer services for the Greek Research and Academic Community.

    * Make command line / console user interface responses prettier with text formating (colors, bold, etc.)

Kamaki comes with preset default values to all configuration options. All vital configuration options are set to use the okeanos.grnet.gr cloud services. User information is not included and should be provided either through the kamaki config command or by editing the configuration file.

If a user needs to switch between different setups, Kamaki can explicitly load configuration files with the --config option:

All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::

    kamaki store list -o global.account=anotheraccount -o global.token=aT0k3n==

A simple way to create the configuration file is to set a configuration option using the kamaki config command. For example::

    kamaki config set account myusername@mydomain.com

The configuration file is formatted so that it can be parsed by the python ConfigParser module. It consists of command sections that are denoted with brackets. Every section contains variables with values. For example::

    [store]

    url=https://okeanos.grnet.gr/pithos

    account=myaccount@mydomain.com

The [global] group is treated by kamaki as a generic group for arbitrary options, and it is used as a super-group for vital Kamaki options, namely account, token, url, cli. This feature does not work for types of configuration options. For example if global.account option is set and store.account option is not set, store services will use the global.account option instead. In case of conflict, the most specific options override the global ones.

    enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored

    the path of a simple file for inter-session kamaki history. Make sure kamaki is executed in a context where this file is accessible for reading and writing. Kamaki automatically creates the file if it doesn't exist

After that, users can run "kamaki test" commands to unit-test the prepackaged client APIs. Unit-tests are still experimental and there is a high probability of false alarms due to some of the expected values being hard-coded in the testing code.

What's more, kamaki offers a clients API that allows the development of external applications for synnefo. The clients API is listed in the `Clients lib <clients.html>`_ section. The recommended method of utilizing this API is explained in the present.

Kamaki interfaces rely on a list of configuration options. In the initial state, kamaki is configured to communicate with the Okeanos IaaS. A detailed guide for setting up kamaki can be found in the `Setup <setup.html>`_ section.

To use the storage service, a user should also provide the corresponding user-name:

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

Kamaki users can access synnefo services through either the interactive shell or the one-command behaviors. In practice, both systems rely on the same command set implementations and API clients, with identical responses and error messages. Still, there are some differences.

* session history with "up" / "down" keys

* shorter commands with command context switching

^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^

--------

The "server" command group is also referred in the following example.

Client commands can feature an arbitrary number of terms:

Although there are no multi-termed client commands until version 0.6.1 , the feature is supported and might be used in feature extensions.

The commands supported in version 0.6.1 are described bellow, grouped by service. The examples showcase a sample set of group commands. The kamaki interactive shell has been chosen as the execution environment:

^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^

    * Download pasted file to local file system *

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

^^^^^^^^^^

    Example 4.1.2: Cyclades help contains all first-level commands of Cyclades command group

    Example 4.1.3: Help for command "server list" with syntax, description and available user options

^^^^^^^^^^^^^

^^^^^

In case of errors, kamaki in debug mode shows useful debug information, like the stack trace, instead of a user-friendly error message. Kamaki also suppresses various warning messages that are also allowed in debug mode.

Most kamaki commands are translated into http requests. Kamaki clients API translated the semantics to REST and handles the response. Users who need to have access to these commands can use the verbose mode that presents the HTTP Request details as well as the full server response.

^^^^^^^^^^^^^^^^^^^^

The -o argument can be used to override temporarily various (set or unset) options. In one command, all -o options are forgotten just after the command had been completed, and the previous settings are restored (the configuration file is not modified).

The astakos-authenticate command in example 4.4.1 run against an explicitly provided token, which temporarily overrode the token provided in the configuration file.

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

^^^^^^^^^^^^^^^^

The kamaki interactive shell implements the notion of command contexts. Each command group is also a context where the users can **enter** by typing the group name. If the context switch is successful, the kamaki shell prompt changes to present the new context ("store" in example 5.1.1).

    Example 5.1.1: Enter store commands context / group

Type **exit** or **ctrl-D** to exit a context and return to the context of origin. If already at the top context (kamaki), an exit is equivalent to exiting the program.

Using Help

^^^^^^^^^^

In context-level, there is a distinction between kamaki-commands and interactive shell commands. The former are available in one-command mode and are related to the cloud client setup and use, while the later are context-shell functions.

    <arguments and possible extensions>

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When working in a context, it is often useful to access other contexts or top-level commands. Kamaki offers access to top-level commands by using the / prefix, as shown bellow::

It is often the case that a user who works in the context command, needs to create a new VM, but doesn't know the flavor or image id of preference. Therefore, it is necessary to list all available flavors (flavor-list) or images (image-list. Both commands belong to different contexts.

An other example (5.3.2) showcases how to acquire and modify configuration settings from a different context. In this scenario, the user token expires at server side while the user is working. When that happens, the system responds with an *(401) UNAUTHORIZED* message. The user can acquires a new token (with a browser) which has to be set to kamaki.

Using config

^^^^^^^^^^^^

The configuration mechanism of kamaki is detailed at the `setup section <setup.html>`_ and it is common for both interaction modes. In specific, the configuration mechanism is implemented as a command group, namely *config*. Using the config commands is as straightforward as any other kamaki commands.

It is often useful to set, delete or update a value. This can be managed either inside the config context or from any command context by using the / detour.

In example 5.4.1 the user is going to work with only one storage container. The store commands use the container:path syntax, but if the user could set a container as a default, the container name could be omitted in most cases. This is possible by setting a store.container setting.

.. warning:: In some cases, the config setting updates are not immediately effective. If that is the case, they will be after the next command run, whatever that command is.

Using history

^^^^^^^^^^^^^

Session history is only available in interactive shell mode. Users can iterate through past commands in the same session by with the *up* and *down* keys. Session history is not stored, although syntactically correct commands are recorded through the permanent history mechanism

^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^