Commit 1576d993 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Merge branch 'feature-docs' into develop

parents 68d68112 1c366ac9
......@@ -11,10 +11,10 @@ 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 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
OpenStack compute, OpenStack object-store and Image 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*).
*storage*).
Setup a client instance
-----------------------
......@@ -45,7 +45,7 @@ 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 used by kamaki as
of `endpoints`. These `endpoints` are 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.
......@@ -56,7 +56,7 @@ Here are instructions for getting the base_url for a service::
(Example 1.2)
2. Use them to instantiate an AstakosClient
(Example 1.2)
3. Use AstakosClient instance to get the endpoints of the service of interest
3. Use AstakosClient instance to get endpoints for the service of interest
(Example 1.3)
4. The 'publicURL' endpoint is the base_url we are looking for
(Example 1.3)
......@@ -99,10 +99,11 @@ clients only need the one labeled as ``publicURL``.
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
storage.StorageClient, pithos.PithosClient --> object-store
compute.ComputeClient, cyclades.CycladesClient --> compute
network.NetworkClient, cyclades.CycladesNetworkClient --> network
image.ImageClient --> image
astakos.AstakosClient --> identity, account
Use client methods
------------------
......
......@@ -6,22 +6,27 @@ APIs code
Command Specifications
----------------------
user
^^^^
astakos
^^^^^^^
Features: user, project, quota, resource, commission, endpoint, service
.. automodule:: kamaki.cli.commands.astakos
:members:
:undoc-members:
cyclades (server, flavor, network)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
cyclades
^^^^^^^^
Features server, flavor
.. automodule:: kamaki.cli.commands.cyclades
:members:
:undoc-members:
pithos (file)
^^^^^^^^^^^^^
pithos
^^^^^^
Features file, container, sharer, group
.. automodule:: kamaki.cli.commands.pithos
:members:
......@@ -30,129 +35,68 @@ pithos (file)
image
^^^^^
.. automodule:: kamaki.cli.commands.image
:members:
:undoc-members:
Kamaki commands
^^^^^^^^^^^^^^^
config
""""""
.. automodule:: kamaki.cli.commands.config
:members:
:undoc-members:
history
"""""""
Features (image, imagecompute)
.. automodule:: kamaki.cli.commands.history
:members:
:undoc-members:
Command Line Interfaces
-----------------------
argument
^^^^^^^^
.. automodule:: kamaki.cli.argument
.. automodule:: kamaki.cli.commands.image
:members:
:show-inheritance:
:undoc-members:
command_shell
^^^^^^^^^^^^^
.. automodule:: kamaki.cli.command_shell
:members:
:show-inheritance:
:undoc-members:
network
^^^^^^^
command_tree
^^^^^^^^^^^^
Features network, port, subnet, ip
.. automodule:: kamaki.cli.command_tree
.. automodule:: kamaki.cli.commands.network
:members:
:show-inheritance:
:undoc-members:
Kamaki commands
^^^^^^^^^^^^^^^
config
^^^^^^
""""""
.. automodule:: kamaki.cli.config
.. automodule:: kamaki.cli.commands.config
:members:
:show-inheritance:
:undoc-members:
errors
^^^^^^
.. automodule:: kamaki.cli.errors
:members:
:show-inheritance:
:undoc-members:
history
^^^^^^^
.. automodule:: kamaki.cli.history
:members:
:show-inheritance:
:undoc-members:
utils
^^^^^
.. automodule:: kamaki.cli.utils
.. automodule:: kamaki.cli.commands.errors
:members:
:show-inheritance:
:undoc-members:
.. _the-client-api-ref:
The clients API
---------------
Modules list
^^^^^^^^^^^^
compute REST API
^^^^^^^^^^^^^^^^
compute
^^^^^^^
.. automodule:: kamaki.clients.compute.rest_api
:members:
:show-inheritance:
:undoc-members:
compute
^^^^^^^
.. automodule:: kamaki.clients.compute
:members:
:show-inheritance:
:undoc-members:
cyclades REST API
^^^^^^^^^^^^^^^^^
cyclades
^^^^^^^^
.. automodule:: kamaki.clients.cyclades.rest_api
:members:
:show-inheritance:
:undoc-members:
cyclades
^^^^^^^^
.. automodule:: kamaki.clients.cyclades
:members:
:show-inheritance:
......@@ -167,17 +111,14 @@ storage
:show-inheritance:
:undoc-members:
pithos_rest_api
^^^^^^^^^^^^^^^
pithos
^^^^^^
.. automodule:: kamaki.clients.pithos.rest_api
:members:
:show-inheritance:
:undoc-members:
pithos
^^^^^^
.. automodule:: kamaki.clients.pithos
:members:
:show-inheritance:
......@@ -191,20 +132,21 @@ image
:show-inheritance:
:undoc-members:
astakos
network
^^^^^^^
.. automodule:: kamaki.clients.astakos
.. warning:: For synnefo, the suggested network implementation is in
kamaki.clients.cyclades.CycladesNetworkClient extension
.. automodule:: kamaki.clients.network
:members:
:show-inheritance:
:undoc-members:
astakos
^^^^^^^
utils
^^^^^
.. automodule:: kamaki.clients.utils
.. automodule:: kamaki.clients.astakos
:members:
:show-inheritance:
:undoc-members:
......@@ -27,23 +27,31 @@ configuration types can also be created and managed in the same fashion as the
Kamaki preset global options, as they appear in the configuration file::
[global]
default_cloud=
colors=off
log_file=${HOME}/.kamaki.log
log_token=off
log_data=off
log_pid=off
max_threads=7
history_file=${HOME}/.kamaki.history
user_cli=astakos
file_cli=pithos
server_cli=cyclades
flavor_cli=cyclades
network_cli=cyclades
ip_cli=cyclades
image_cli=image
config_cli=config
history_cli=history
project_cli = astakos
default_cloud = my_cloud
quota_cli = astakos
file_cli = pithos
subnet_cli = network
history_cli = history
group_cli = pithos
server_cli = cyclades
container_cli = pithos
imagecompute_cli = image
user_cli = astakos
network_cli = network
resource_cli = astakos
config_cli = config
flavor_cli = cyclades
sharer_cli = pithos
image_cli = image
port_cli = network
ip_cli = network
history_file = /home/someuser/.kamaki.history
colors = off
log_pid = off
log_token = off
log_data = off
log_file = /home/someuser/.kamaki.log
A cloud configuration is required to make kamaki run. The
`setup guide <../setup.html>`_ can help when setting one or more cloud
......
Listing
=======
In this section we present the ways of kamaki for listing, an operation that is
common to most command groups.
The examples of this section run in a kamaki interactive shell.
.. code-block:: console
$ kamaki
kamaki v0.10 - Interactive Shell
/exit terminate kamaki
exit or ^D exit context
? or help available commands
?command help on command
!<command> execute OS shell command
Session user is Tyler Durden <uuid: th3y-4r3-7h3-54m3-p3r50n>
[kamaki]:
The listing of various synnefo objects (e.g, server, file, network) is
showcased in this section.
Simple listing
--------------
......@@ -27,45 +11,70 @@ List configuration options, whether in the file or from defaults list
.. code-block:: console
[kamaki]: config list
cloud.default.url = https://astakos.example.com/identity/v2.0/
cloud.default.token = my70k3n==
global.default_cloud = default
global.colors = on
$ kamaki config list
global.default_cloud = mycloud
global.colors = off
global.config_cli = config
global.container_cli = pithos
global.file_cli = pithos
global.flavor_cli = cyclades
global.group_cli = pithos
global.history_cli = history
global.history_file = /home/saxtouri/.kamaki.history
global.history_file = /home/someuser/.kamaki.history
global.image_cli = image
global.log_file = /home/saxtouri/.kamaki.log
global.log_token = one
global.max_threads = 5
global.network_cli = cyclades
global.imagecompute_cli = image
global.ip_cli = network
global.log_data = off
global.log_file = /home/someuser/.kamaki.log
global.log_pid = off
global.log_token = off
global.network_cli = network
global.port_cli = network
global.project_cli = astakos
global.quota_cli = astakos
global.resource_cli = astakos
global.server_cli = cyclades
global.sharer_cli = pithos
global.subnet_cli = network
global.user_cli = astakos
[kamaki]:
List stored containers and then objects in container "pithos"
List stored containers and file or directory objects in container "pithos"
.. code-block:: console
[kamaki]: file list
$ kamaki container list
pithos (36MB, 4 objects)
trash (0B, 0 objects)
[kamaki]: file list pithos
. 2KB info.txt
. D video/
. 11MB video/tk1.mpg
. 12MB video/tk2.mpg
. 13MB video/tk3.mpg
[kamaki]:
$ kamaki file list /pithos
2KB info.txt
D video/
11MB video/tk1.mpg
12MB video/tk2.mpg
13MB video/tk3.mpg
$ kamaki file list /pithos/video
11MB video/tk1.mpg
12MB video/tk2.mpg
13MB video/tk3.mpg
.. note:: In file list, the default container is "pithos"
.. code-block:: console
$ kamaki file list
2KB info.txt
D video/
11MB video/tk1.mpg
12MB video/tk2.mpg
13MB video/tk3.mpg
$ kamaki file list video
11MB video/tk1.mpg
12MB video/tk2.mpg
List virtual machines (servers)
.. code-block:: console
[kamaki]: server list
$ kamaki server list
4201 example server 1
4202 example server 2
4203 example server 3
......@@ -77,25 +86,23 @@ List networks
.. code-block:: console
[kamaki]: network list
$ kamaki network list
1 public_network
42 my_private_network
[kamaki]:
List flavors
.. code-block:: console
[kamaki]: flavor list
$ kamaki flavor list
1 C1R1024D20drbd
2 C1R1024D30drbd
[kamaki]:
List images from Image API and from Compute APIs
.. code-block:: console
[kamaki]: image list
$ kamaki image list
f1r57-1m4g3-1d Debian Base Alpha
container_format: bare
disk_format: diskdump
......@@ -106,26 +113,18 @@ List images from Image API and from Compute APIs
disk_format: diskdump
size: 474066944
status: available
[kamaki]: image compute list
$ kamaki imagecompute list
f1r57-1m4g3-1d Debian Base Alpha
53c0nd-1m4g3-1d Beta Debian Base
[kamaki]:
Detailed pithos listing
-----------------------
Enter contect
.. code-block:: console
[kamaki]: file
[file]:
List pithos containers with details
.. code-block:: console
[file]: list -l
$ kamaki container list -l
pithos
bytes: 0 (0B)
count: 3
......@@ -140,49 +139,28 @@ List pithos containers with details
policy:
quota: 0
versioning: auto
[file]:
Create some more pithos container to experiment with
Create some more containers to experiment with
.. code-block:: console
[file]: create cont1
[file]: create cont2
[file]: create cont3
[file]: create cont4
[file]: list
$ kamaki container create cont1
$ kamaki container create cont2
$ kamaki container create cont3
$ kamaki container create cont4
$ kamaki container list
cont1 (0B, 0 objects)
cont2 (0B, 0 objects)
cont3 (0B, 0 objects)
cont4 (0B, 0 objects)
pithos (36B, 5 objects)
trash (0B, 0 objects)
[file]:
List only 3, then list three by three
.. code-block:: console
[file]: list -n 3
cont1 (0B, 0 objects)
cont2 (0B, 0 objects)
cont3 (0B, 0 objects)
[file]: list -n 3 --more
cont1 (0B, 0 objects)
cont2 (0B, 0 objects)
cont3 (0B, 0 objects)
(3 listed - 3 more - "enter" to continue)
<enter is pressed>
cont4 (0B, 0 objects)
pithos (36B, 4 objects)
trash (0B, 0 objects)
[file]:
List contents of container `pithos`
.. code-block:: console
[file]: list -l pithos
$ kamaki file list -l /pithos
info.txt
by: s0m3-u53r-1d
bytes: 2000 (2ΚB)
......@@ -232,13 +210,14 @@ List contents of container `pithos`
type: video/mpeg
uuid: 4195e8c3-9b9a-4e97-8c20-fdfef34892fe
version: 1083
[kamaki]:
$ kamaki
List only objects starting with "video" and exit "file" context
List only objects starting with "video" and exit "file" context. Remember that
"pithos" is the default container, so there is no need to refer to it.
.. code-block:: console
[file]: list -l pithos:video/
$ kamaki file list -l video/
video/tk1.mpg
by: s0m3-u53r-1d
bytes: 11000000 (11ΜΒB)
......@@ -269,36 +248,21 @@ List only objects starting with "video" and exit "file" context
uuid: 4195e8c3-9b9a-4e97-8c20-fdfef34892fe
version: 1083
Exit context
.. code-block:: console
[file]: exit
[kamaki]:
Detailed Server Listing
-----------------------
Enter context
.. code-block:: console
[kamaki]: server
[server]:
List only 3, then list three by three, all with enumeration
.. code-block:: console
[server]: list -n 3 --enumerate
$ kamaki server list --enumerate
1. 4201 example server 1
2. 4202 example server 2
3. 4203 example server 3
4. 4204 example server 4
5. 4205 example server 5
6. 4206 example server 6
[server]: list -n 3 --more --enumerate
$ kamaki server list -n 3 --more
1. 4201 example server 1
2. 4202 example server 2
3. 4203 example server 3
......@@ -307,13 +271,12 @@ List only 3, then list three by three, all with enumeration
4. 4204 example server 4
5. 4205 example server 5
6. 4206 example server 6
[server]:
Get json output returned by the compute API server (only first two VMs)
List in json output
.. code-block:: console
[server]: list -j -n 2
$ kamaki server list -output-format=json
[
{
"name": "example server 1",
......@@ -343,14 +306,14 @@ Get json output returned by the compute API server (only first two VMs)
],
"id": 4202
}
...
]
[server]:
Server details (first two only)
Server details
.. code-block:: console
[server]: list -l -n 2
$ kamaki server list -l
4201 my example server 1
accessIPv4:
accessIPv6:
......@@ -483,32 +446,16 @@ Server details (first two only)
tenant_id: s0m3-u53r-1d
updated: 2013-06-17T07:57:50.054550+00:00
user_id: s0m3-u53r-1d
[server]:
Exit context
.. code-block:: console
[server]: exit
[kamaki]:
.. note:: `network` and `flavor list` behave in the same way as `server list`
...
Detailed image listing
----------------------
Enter context