Skip to content

GitLab

Commit 16d7b9ff authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Update and correct kamaki.clients documentation

parent 97086fcd
Hide whitespace changes
Inline Side-by-side
docs/commands.rst
View file @ 16d7b9ff
......@@ -143,16 +143,16 @@ server (Compute/Cyclades)
.. code-block:: text
addr : List a server's nic address
addr : List a server nic address
console : Get a VNC console
create : Create a server
delete : Delete a server
firewall: Manage server's firewall profile
set : Set the server's firewall profile
get : Get the server's firewall profile
firewall: Manage server firewall profile
set : Set the server firewall profile
get : Get the server firewall profile
ip : Manage floating IPs for the servers
attach: Attach a floating ip to a server with server_id
info : A floating IPs' details
info : A floating IP details
detach: Detach floating ip from server
list : List all floating ips
create: Create a new floating IP
......@@ -165,7 +165,7 @@ server (Compute/Cyclades)
set : Add / update server metadata
delete: Delete a piece of server metadata
reboot : Reboot a server
rename : Update a server's name
rename : Update a server name
shutdown: Shutdown a server
start : Start a server
stats : Get server statistics
......@@ -445,12 +445,12 @@ Showcase: Upload and download a file
-rw-rw-r-- 1 ******** ******** 20M Nov 26 15:42 rndm_remote.file
[file]: !diff rndm_local.file rndm_remote.file
.. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g. bash)
.. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g., bash)
.. warning:: The container:object/path syntax does not function if the
container and / or the object path contain one or more : characters. To use
containers and objects with : use the --container and --dst-container
arguments, e.g. to copy test.py object from example:dev container to
arguments, e.g., to copy test.py object from example:dev container to
example:deploy ::
$ kamaki file copy --container=example:dev test.py --dst-container=example:deploy
docs/developers/adding-commands.rst
View file @ 16d7b9ff
......@@ -2,29 +2,31 @@ Adding Commands
===============
Kamaki commands are implemented as python classes, decorated with a special
decorator called *command*. This decorator is a method of kamaki.cli that adds
a new command in a CommandTree structure (kamaki.cli.commant_tree). The later
is used by interfaces to manage kamaki commands.
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.
In the following, a set of kamaki commands will be implemented::
For demonstration purposes, the following set of kamaki commands will be
implemented in this document::
mygrp1 list all //show a list
mygrp1 list details [--match=<>] //show list of details
mygrp2 list all [regular expression] [-l] //list all subjects
mygrp2 info <id> [name] //get information for subject with id
There are two command sets to implement, namely mygrp1 and mygrp2. The first
will contain two commands, namely list-all and list-details. The second one
will also contain two commands, list-all and info. To avoid ambiguities,
command names should rather be prefixed with the group they belong to, e.g.
mygrp1-list-all and mygrp2-list-all.
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 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 argument and an optional runtime flag argument. The
last is an example of a command with an obligatory and an optional argument.
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.
Samples of the expected behavior in one-command mode are following:
Examples of the expected behavior in one-command mode:
.. code-block:: console
......@@ -35,34 +37,32 @@ Samples of the expected behavior in one-command mode are following:
- - - -
list
$ kamaki mygrp1 list
Syntax Error
Options
- - - -
all show a list
details show a list of details
$ kamaki mygrp1 list all
... (mygrp1 client method is called) ...
... (a mygrp1_list_all instance runs) ...
$ kamaki mygrp2 list all 'Z[.]' -l
... (mygrp2 client method is called) ...
... (a mygrp2_list_all instance runs) ...
$
The above example will be used throughout the present guide.
The CommandTree structure
-------------------------
CommandTree manages a command by its path. Each command is stored in multiple
nodes on the tree, so that the last term is a leaf and the route from root to
that leaf represents the command path. For example the commands *file upload*,
*file list* and *file info* are stored together as shown bellow::
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::
- file
''''''''|- info
|- list
|- upload
The example used in the present, should result to the creation of two trees::
Now, let's load the showcase example on CommandTrees::
- mygrp1
''''''''|- list
......@@ -74,12 +74,12 @@ The example used in the present, should result to the creation of two trees::
'''''''|- all
|- info
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*
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.
A command group information (name, description) is provided at CommandTree
structure initialization:
The first name of the command path and a description (name, description) are needed to initializeg a CommandTree:
.. code-block:: python
......@@ -88,15 +88,19 @@ structure initialization:
_commands = [_mygrp1_commands, _mygrp2_commands]
The command decorator
---------------------
The *command* decorator mines all the information necessary to build a command
specification which is then inserted in a CommanTree instance::
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::
class code ---> command() --> updated CommandTree structure
Kamaki interfaces make use of this CommandTree structure. Optimizations are
Kamaki interfaces make use of the CommandTree structure. Optimizations are
possible by using special parameters on the command decorator method.
.. code-block:: python
......@@ -108,14 +112,16 @@ possible by using special parameters on the command decorator method.
:param prefix: of the commands allowed to be inserted ('' for all)
:param descedants_depth: is the depth of the tree descedants of the
:param descedants_depth: is the depth of the tree descendants of the
prefix command.
"""
Creating a new command specification set
----------------------------------------
A command specification developer should create a new module (python file) with as many classes as the command specifications to be offered. Each class should be decorated with *command*.
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*.
.. code-block:: python
......@@ -129,10 +135,10 @@ A command specification developer should create a new module (python file) with
...
A list of CommandTree structures must exist in the module scope, with the name
_commands, as shown above. Different CommandTree objects correspond to
different command groups.
*_commands*. Different CommandTree objects correspond to different command
groups.
Get command description
Set command description
-----------------------
The description of each command is the first line of the class commend. The
......@@ -143,25 +149,50 @@ subject with id*" description.
...
@command(_mygrp2_commands)
class mygrp2_info()
"""get information for subject with id"""
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.
Declare run-time argument
-------------------------
The argument mechanism allows the definition of run-time arguments. Some basic
argument types are defined at the
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
`argument module <code.html#module-kamaki.cli.argument>`_, but it is not
uncommon to extent these classes in order to achieve specialized type checking
and syntax control (e.g. at
`pithos cli module <code.html#module-kamaki.cli.commands.pithos>`_).
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 object class should
initialize a dict called *arguments* , where Argument objects are stored. Each
argument object is a possible run-time argument. Syntax checking happens at
client level, while the type checking is implemented in the Argument code
(thus, many different Argument types might be needed).`
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).
.. code-block:: python
......@@ -190,15 +221,15 @@ or more usually and elegantly:
arguments = dict(
match=ValueArgument(
'Filter output to match string', ('-m', --match'))
'Filter output to match string', ('-m', --match'))
)
Accessing run-time arguments
----------------------------
To access run-time arguments, users can use the _command_init interface, which
implements __item__ accessors to handle run-time argument values. In specific,
an instance of _command_init can use brackets to set or read <argument>.value .
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>]*.
.. code-block:: python
......@@ -222,9 +253,8 @@ an instance of _command_init can use brackets to set or read <argument>.value .
The main method and command parameters
--------------------------------------
The command behavior for each command / class is coded in *main*. The
parameters of *main* method defines the command parameters part of the syntax.
In specific::
The command behavior for each command class is coded in *main*. The
parameters of *main* method affect the syntax of the command. In specific::
main(self, param) - obligatory parameter <param>
main(self, param=None) - optional parameter [param]
......@@ -236,8 +266,8 @@ In specific::
main(self, *args) - arbitary number of params [...]
main(self, param1____param2, *args) - <param1:param2> [...]
The information that can be mined by *command* for each individual command is
presented in the following:
Let's have a look at the command specification class again, and highlight the
parts that affect the command syntax:
.. code-block:: python
:linenos:
......@@ -245,23 +275,32 @@ presented in the following:
from kamaki.cli.argument import FlagArgument
...
_commands = [_mygrp1_commands, _mygrp2=commands]
_commands = [_mygrp1_commands, _mygrp2_commands]
...
@command(_mygrp2_commands)
class mygrp2_list_all():
"""List all subjects"""
"""List all subjects
Refers to the subject accessible by current user
"""
arguments = dict(FlagArgument('detailed list', '-l'))
def main(self, reg_exp=None):
...
This will load the following information on the CommandTree:
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
* Syntax (from lines 8,12,19): mygrp list all [reg exp] [-l]
* Description (form line 9): List all subjects
* Arguments help (from line 13,14): -l: 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.
Letting kamaki know
-------------------
......@@ -270,11 +309,11 @@ Kamaki will load a command specification *only* if it is set as a configurable
option. To demonstrate this, let the command specifications coded above be
stored in a file named *grps.py*.
The developer should move file *grps.py* to kamaki/cli/commands, the default
place for command specifications, although running a command specification from
a different path is also a kamaki feature.
The developer should move the file *grps.py* to *kamaki/cli/commands*, the
default place for command specifications
The user has to use a configuration file where the following is added:
These lines should be contained in the kamaki configuration file for a new
command specification module to work:
::
[global]
......@@ -288,9 +327,10 @@ or equivalently:
$ kamaki config set mygrp1_cli grps
$ kamaki config set mygrp2_cli grps
Command specification modules don't need to live in kamaki/cli/commands,
although this is suggested for uniformity. If a command module exist in another
path::
.. 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.
::
[global]
mygrp_cli = /another/path/grps.py
......@@ -319,13 +359,23 @@ Summary: create a command set
# Define command specifications
@command(_mygrp1_commands)
class mygrp1_list(_command_init):
"""List mygrp1 objects.
There are two versions: short and detailed
"""
@command(_mygrp1_commands)
class mygrp1_list_all(_command_init):
"""show a list"""
def main(self):
def _run():
...
def main(self):
self._run()
@command(_mygrp1_commands)
class mygrp1_list_details(_command_init):
......@@ -336,11 +386,16 @@ Summary: create a command set
'Filter output to match string', ('-m', --match'))
)
def main(self):
...
def _run(self):
match_value = self['match']
...
def main(self):
self._run()
#The following will also create a mygrp2_list command with no description
@command(_mygrp2_commands)
class mygrp2_list_all(_command_init):
......@@ -350,21 +405,23 @@ Summary: create a command set
list=FlagArgument('detailed listing', '-l')
)
def main(self, regular_expression=None):
...
detail_flag = self['list']
def _run(self, regexp):
...
if detail_flag:
if self['list']:
...
...
if regular_expression:
else:
...
...
def main(self, regular_expression=None):
self._run(regular_expression)
@command(_mygrp2_commands)
class mygrp2_info(_command_init):
"""get information for subject with id"""
def main(self, id, name=''):
def _run(self, grp_id, grp_name):
...
def main(self, id, name=''):
self._run(id, name)
docs/developers/clients-api.rst
View file @ 16d7b9ff
......@@ -3,28 +3,31 @@ Creating applications with kamaki API
Kamaki features a clients API for building third-party client applications that
communicate with OpenStack and / or Synnefo cloud services. The package is
called kamaki.clients and servers as a lib.
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.
A showcase of an application built on *kamaki.clients* is *kamaki.cli*, the
command line interface of kamaki.
Since Synnefo services are build as OpenStack extensions, an inheritance
approach has been chosen for implementing clients for both. In specific,
the *compute*, *storage* and *image* modules are clients of the OS compute, OS
object-store, respectively. On the contrary, all the other modules are Synnefo
extensions (*cyclades* extents *compute*, *pithos* and *pithos_rest_api*
extent *storage*) or novel Synnefo services (e.g., *astakos* for IM, *image*
for *plankton*).
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*).
Setup a client instance
-----------------------
External applications may instantiate one or more kamaki clients.
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.
.. code-block:: python
:emphasize-lines: 1
Example 1.1: Instantiate Cyclades and Pithos client
Example 1.1: Instantiate Cyclades and Pithos clients
from kamaki.clients.cyclades import CycladesClient
......@@ -33,21 +36,21 @@ External applications may instantiate one or more kamaki clients.
my_cyclades_client = CycladesClient(base_url, token)
my_pithos_client = PithosClient(base_url, token, account, container)
.. note:: *cyclades* and *pithos* clients inherit all methods of *compute*
and *storage* clients respectively. Separate compute or storage objects
should be used only when implementing applications for strict OS Compute or
OS Storage services.
.. 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.
Using endpoints to get the base_url
-----------------------------------
In OpenStack, each service (e.g. `compute`, `object-store`, etc.) has a number
of `endpoints`. These `endpoints` are actually URIs that are needed as prefixes
for the API calls the kamaki client generates. In this context, we need just
one of these these `endpoints`, the `publicURL`, which is also referred to as
`base_url` in kamaki client libraries.
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.
In general, this is the suggested way of getting the base_url::
Here are instructions for getting the base_url for a service::
1. From the deployment UI get the AUTHENTICATION_URL and TOKEN
(Example 1.2)
......@@ -59,9 +62,9 @@ In general, this is the suggested way of getting the base_url::
(Example 1.3)
The AstakosClient is a client for the Synnefo/Astakos server. Synnefo/Astakos
is an advanced identity server based on OpenStack identity specifications.
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.
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.
Let's review the process with examples.
......@@ -93,24 +96,26 @@ clients only need the one labeled as ``publicURL``.
pithos_endpoints = my_astakos_client.get_service_endpoints('object-store')
pithos_base_url = pithos_endpoints['publicURL']
The ``get_service_endpoints`` method gets the service name as an argument. Here
are the service names for the most popular kamaki clients::
The ``get_service_endpoints`` method is called with the service name as an
argument. Here are the service names for the kamaki clients::
storage, pithos --> object-store
compute, cyclades --> compute
image --> image
astakos --> identity
storage.StorageClient, pithos.PithosClient --> object-store
compute.ComputeClient, cyclades.CycladesClient --> compute
image.ImageClient --> image
astakos.AstakosClient --> identity, account
Use client methods
------------------
Client methods can now be called. Developers are advised to
consult :ref:`the-client-api-ref` for details on the available methods and how
to use them.
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`
In the following example, the *cyclades* and *pithos* clients of example 1.1
are used to extract some information, that is then printed to the standard
output.
are used to extract some information through the remote service APIs. The information is then printed to the standard output.
.. code-block:: python
......@@ -119,7 +124,6 @@ output.
Example 1.4: Print server name and OS for server with server_id
Print objects in container mycont
srv = my_cyclades_client.get_server_info(server_id)
print("Server Name: %s (with OS %s" % (srv['name'], srv['os']))
......@@ -130,7 +134,7 @@ output.
.. code-block:: console
:emphasize-lines: 1
Run of examples 1.1 + 1.4
* A run of examples 1.1 + 1.4 *
$ python test_script.py
......@@ -143,14 +147,14 @@ output.
Error handling
--------------
The kamaki.clients standard error is ClientError. A ClientError is raised for
any kind of kamaki.clients errors (errors reported by servers, type errors in
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
arguments, etc.).
A ClientError contains::
message The error message.
status An optional error code, e.g. after a server error.
status An optional error code, e.g., after a server error.
details Optional list of messages with error details.
The following example concatenates examples 1.1 to 1.4 plus error handling
......@@ -159,12 +163,15 @@ The following example concatenates examples 1.1 to 1.4 plus error handling
Example 1.5: Error handling
from kamaki.clients import ClientError
from kamaki.clients.astakos import AstakosClient
from kamaki.clients.cyclades import CycladesClient
from kamaki.clients.pithos import PithosClient
try:
my_astakos_client = AstakosClient(AUTHENTICATION_URL, TOKEN)
my_astakos_client.authenticate()
except ClientError:
print('Failed to authenticate user token')
return 1
......@@ -297,3 +304,42 @@ Register a banch of pre-uploaded images
print 'Image %s registered with id %s' % (r['name'], r['id'])
except ClientError:
print 'Failed to register image %s' % IMAGE_PATH
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'