Commit 2bd23362 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Change VMs to servers in docs, fix docs scripts

parent c99f24db
......@@ -54,17 +54,33 @@
from sys import path, stderr
import os
SITE_PACKAGES_PATH = os.path.expanduser(
'~/src/kamaki/docsenv/lib/python2.7/site-packages')
try:
from objpool.http import PooledHTTPConnection
PooledHTTPConnection
except ImportError:
stderr.write("`objpool` package is required to build kamaki docs.\n")
path.insert(0, SITE_PACKAGES_PATH)
try:
from objpool.http import PooledHTTPConnection
PooledHTTPConnection
except ImportError:
stderr.write("`objpool` package is required to build kamaki docs.\n")
exit(1)
try:
from progress.bar import ShadyBar
ShadyBar
except ImportError:
stderr.write("`progress` package is required to build kamaki docs.\n")
path.insert(0, SITE_PACKAGES_PATH)
try:
from progress.bar import ShadyBar
ShadyBar
except ImportError:
stderr.write("`progress` package is required to build kamaki docs.\n")
exit(1)
path.insert(0, os.path.join(os.path.abspath(os.path.dirname(__file__)), '..'))
......
......@@ -90,7 +90,7 @@ Install mock (for developers only)
$ sudo apt-get install python-mock=1.0.1
.. hint:: To activate functional tests in kamaki. enable the preconfigured
.. hint:: To activate functional tests in kamaki enable the preconfigured
*livetest* command group:
.. code-block:: console
......@@ -98,24 +98,6 @@ Install mock (for developers only)
$ kamaki config set livetest_cli livetest
Install astakosclient (optional)
""""""""""""""""""""""""""""""""
A seperate project called
`astakosclient <https://pypi.python.org/pypi/astakosclient>`_ can be used for
advanced user and service management.
.. code-block:: console
$ apt-get install python-astakosclient
.. hint:: To activate astakosclient commands in kamaki, enable the
preconfigured *astakos* command group:
.. code-block:: console
$ kamaki config set astakos_cli astakos
.. _installing-from-pypi-ref:
Installing from pypi
......@@ -136,7 +118,7 @@ Optional:
Setup a virtual enviroment (optional)
"""""""""""""""""""""""""""""""""""""
With virtualenv users can setup kamaki and Synnefo services in a sandbox
Use virtualenv to setup kamaki and Synnefo services in a sandbox
environment.
.. code-block:: console
......@@ -187,28 +169,11 @@ mock.
$ kamaki config set livetest_cli livetest
Install astakosclient
"""""""""""""""""""""
A seperate project called
`astakosclient <https://pypi.python.org/pypi/astakosclient>`_ can be used for
advanced user and service management.
.. code-block:: console
$ pip install astakosclient
.. hint:: To activate astakosclient commands in kamaki, enable the
preconfigured *astakos* command group:
.. code-block:: console
$ kamaki config set astakos_cli astakos
Mac OS X
--------
Kamaki can be installed on Mac OS X systems from source, by following the steps
Kamaki can be installed on Mac OS X systems, by following the steps
at :ref:`installing-from-pypi-ref`.
Windows
......@@ -226,7 +191,7 @@ Requirements
* Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
Users who have already set up and wokring python and setuptools (e.g., for
Users who have already set up python and setuptools (e.g., for
another project) may skip Python and / or setuptools installation.
Install Python
......@@ -264,10 +229,10 @@ According to the corresponding
`python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools
installer doesn't currently work on 64bit machines.
* Users with 32-bit operating systems should download and run the graphic
* Users with 32-bit platforms should download and run the graphic
installer
* Users with 64-bit machines should download the
* Users with 64-bit platforms should download the
`ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_ script and
install it from a command shell. In the following example, the script was
downloaded at C:\\Downloads::
......
......@@ -8,13 +8,13 @@ the kamaki config file.
Quick Setup
-----------
Existing kamaki users should consult the
`migration guide <#migrating-from-kamaki-0-8-x-to-0-9>`_ first.
.. warning:: Users of kamaki 0.8.X or older should consult the
`migration guide <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_ first.
Kamaki has to be configured for a specific Synnefo deployment, with an
authentication url and user token pair. Users should also pick an alias to name
the cloud configuration. This can be any single word, e.g., "default", "mycloud"
or whatever suits kamaki users.
the cloud configuration. This can be any single word, e.g., "default",
"mycloud"or whatever suits the user.
.. code-block:: console
......@@ -31,11 +31,11 @@ Otherwise, a default cloud should be specified:
Since version 0.14, Synnefo supports a single authentication URL for retrieving
all API endpoints. This URL is retrieved from the Synnefo Web UI and should be
set as the cloud URL for kamaki. All service-specific URLs are retrieved and
handled automatically by kamaki, through this URL. Users of Synnefo clouds
>=0.14 are advised against using any service-specific URLs.
handled automatically. Users of Synnefo clouds >=0.14 are advised against using
any service-specific URLs.
Migrating from kamaki 0.8.X to 0.9
----------------------------------
Migrating from kamaki 0.8.X to 0.9 or better
--------------------------------------------
This section refers to running installations of kamaki version <= 0.8.X. To
check the current kamaki version:
......@@ -46,10 +46,10 @@ check the current kamaki version:
Existing kamaki users should convert their configuration files to v9. To do
that, kamaki 0.9 can inspect the configuration file and suggests a list of
config file transformations, which are performed automatically (after users'
permission). This mechanism is invoked when an API-related kamaki command is
fired. On example 2.1 we suggest using the `user authenticate` command to fire
the kamaki config file conversion mechanism.
config file transformations, which are performed automatically after users'
permission. This mechanism is invoked when an API-related kamaki command is
fired. On example 2.1 we suggest using the `user authenticate` command to start
the conversion mechanism for the configuration file.
.. code-block:: console
:emphasize-lines: 1
......@@ -78,7 +78,7 @@ the kamaki config file conversion mechanism.
Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
At this point, we should examine the kamaki output. Most options are renamed to
be understood by the new kamaki.
match the latest configuration file version specifications.
Let's take a look at the discarded options:
......@@ -89,14 +89,12 @@ Let's take a look at the discarded options:
meaningless and therefore omitted.
* `global.data_log` option has never been a valid kamaki config option.
In this example, the user accidentally misspelled the term `log_data`
(which is a valid kamaki config option) as `data_log`. To fix this, the
user should set the correct option after the conversion is complete
(Example 2.2).
In this scenario, the user wanted to set the `log_data` option, but he or
she typed `data_log` instead. To fix this, the user should manually set the
correct option after the conversion is complete (Example 2.2).
Users should press *y* when they are ready. Kamaki has now modified the default
config file to conform with kamaki config file v3. Now users should rescue
unrescued information (if any).
Users should press *y* when they are ready, which will cause the default config
file to be modified so that it conforms with the latest version.
.. code-block:: console
:emphasize-lines: 1
......@@ -121,19 +119,16 @@ Multiple clouds
The following refers to users of multiple Synnefo and/or Open Stack
deployments. In the following, a Synnefo or Open Stack cloud deployment will
frequently be called as a **cloud**.
be called **a cloud**.
Kamaki supports accessing multiple clouds from the same kamaki setup. Before
kamaki 0.9, this was possible only by using multiple config files. Since 0.9,
kamaki supports multiple clouds in the same configuration.
Each cloud corresponds to a Synnefo (or Open Stack) cloud deployment.
Since Synnefo version 0.14, each deployment offers a single point of
authentication, as an **authentication URL** and **token** pair. Users can
retrieve this information through the cloud UI.
Multiple clouds can be configured and manager in a single kamaki setup, since
version 0.9. Each cloud corresponds to a Synnefo (or Open Stack) cloud
deployment, with each deployment offering a single point of authentication (an
**authentication URL** and **token** pair). Users can retrieve this information
through the cloud UI.
Once a user has retrieved one URL/token pair per cloud, it is time to assign a
name to each cloud and let kamaki know about them.
name to each cloud and configure kamaki accordingly.
For example, let the user have access to two clouds with the following authentication information ::
......@@ -146,7 +141,7 @@ For example, let the user have access to two clouds with the following authentic
authentication token: my73571ng70k3n==
.. note:: the cloud alias is arbitrary and decided by the user. It is just a
name to call a cloud setup in the kamaki context.
reference label for the cloud setup in the kamaki context.
The user should let kamaki know about these setups:
......@@ -164,9 +159,9 @@ bellow:
.. code-block:: console
$ kamaki config getcloud
$ kamaki config get cloud
cloud.default.url = https://example.com/astakos.identity/v2.0/
cloud.default.url = myd3f4u1770k3n==
cloud.default.token = myd3f4u1770k3n==
cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
cloud.devel.token = myd3v3170k3n==
cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/
......@@ -214,9 +209,25 @@ One way to test this, is the `user athenticate` command:
name : Default User
$
In interactive cell, the cloud is picked when invoking the shell, with
In interactive cell, the cloud can be picked when invoking the shell, with
the **- - cloud** option.
.. code-block:: console
$ kamaki --cloud=devel
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 Devel User
(uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c)
[kamaki]:
Optional features
-----------------
......@@ -233,10 +244,6 @@ For installing any or all of the following, consult the
* Allow unit tests to run on kamaki.clients package
* Needs mock version 1.X or better
* astakosclient
* For advanced users mostly
* Allows the use of a full astakos command line client
Any of the above features can be installed at any time before or after kamaki
installation.
......@@ -247,8 +254,8 @@ There are two kinds of configuration options:
* kamaki-related (global)
interface settings and constants of the kamaki internal mechanism, e.g.,
colors in the output, maximum threads per connection, custom logging or
history files, etc.
terminal colors, maximum threads per connection, custom logging, history
file path, etc.
* cloud-related
information needed to connect and use one or more clouds. There are some
......@@ -284,7 +291,7 @@ explicitly load configuration files with the **- - config** (or **- c**) option
Modifying options at runtime
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example:
.. code-block:: console
......@@ -293,24 +300,26 @@ All kamaki commands can be used with the -o option in order to override configur
will invoke *kamaki file list* with the specified options, but the initial
global.pithos_container values will not be modified.
Editing options
^^^^^^^^^^^^^^^
Kamaki config command allows users to see and manage all configuration options.
* kamaki config list
lists all configuration options currently used by a Kamaki installation
lists all configuration options of a kamaki setup
* kamaki config get <group.option>
show the value of a specific configuration option. Options must be of the
form *group.option*. The term *option* is equivalent to *global.option*
form *group.option*. A single *option* is equivalent to *global.option*,
with the exception of the term *cloud* (see bellow)
* kamaki config set <group.option> <value>
set the group.option to value. If no group is given, the defaults to
set the group.option to value. If no group is given, it defaults to
*global*.
* kamaki config delete <group.option>
delete a configuration option. If no group is given, the defaults to
delete a configuration option. If no group is given, it defaults to
*global*
The above commands cause option values to be permanently stored in the Kamaki configuration file.
......@@ -341,20 +350,29 @@ semantics:
delete the <option> and its value from the cloud cloud aliased as
<cloud alias>
.. note:: To see if a default cloud is configured, get the default_cloud value
To see if a default cloud is configured, get the default_cloud value
.. code-block:: console
$ kamaki config get default_cloud
If no default_cloud value is set, the first cloud alias is picked as default.
To pick a cloud alias as default:
.. code-block:: console
$ kamaki config set default_cloud <cloud alias>
Editing the configuration file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The configuration file is a simple text file that can be created by the user.
.. note:: users of kamaki < 0.9 can use kamaki 0.9.X to automatically convert
their old configuration files to the new config file version (>= 3.0). To
do this, follow `these instructions <#migrating-from-kamaki-0-8-x-to-0-9>`_
.. note:: users of kamaki < 0.9 can use the latest versions to automatically
convert their old configuration files to the new configuration file(s).
See `these instructions <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_
for more.
A simple way to create the configuration file is to set a configuration option
using the kamaki config command. For example:
......@@ -378,28 +396,18 @@ The configuration file is formatted so that it can be parsed by the python Confi
url =
token =
A bunch of configuration options are created and set to their default options,
except the log_file option which is set to whatever the specified value.
The [cloud "default"] section is special and is used to configure the default
cloud cloud. Kamaki will not be able to run without setting the url and token
values to that section.
In this scenario, a bunch of configuration options are created and set to their
default options, except the log_file option which is set to whatever the
specified value.
More clouds can be created on the side of the default cloud, e.g., using the
examples at the `multiple clouds guide <#multiple-clouds>`_ ::
[cloud "devel"]
url = https://devel.example.com/astakos/identity/v2.0/
token = myd3v3170k3n==
[cloud "testing"]
url = https://testing.example.com/astakos/identity/v2.0/
token = my73571ng70k3n==
The *[cloud "default"]* section is special and is used to configure the default
cloud. Kamaki will not be able to do anything useful without proper url and
token values set in the cloud section.
Available options
^^^^^^^^^^^^^^^^^
The [global] group is treated by kamaki as a generic group for kamaki-related
The [*global*] group is treated by kamaki as a generic group for kamaki
settings, namely command cli specifications, the thread limit, console colors,
history and log files, log detail options and pithos-specific options.
......@@ -416,6 +424,10 @@ history and log files, log detail options and pithos-specific options.
allow kamaki to log http data (by default, it logs only method, URL and
headers)
* global.log_pid <on|off>
attach the process name and id that produces each log line. Useful for
resolving race condition problems.
* global.file_cli <UI command specifications for file>
a special package that is used to load storage commands to kamaki UIs.
Don't touch this unless if you know what you are doing.
......@@ -447,27 +459,27 @@ history and log files, log detail options and pithos-specific options.
Additional features
^^^^^^^^^^^^^^^^^^^
The livetest suite
""""""""""""""""""
Functional tests
""""""""""""""""
Kamaki contains a live test suite for the kamaki.clients API, where "live"
means that the tests are performed against active services that up and running.
The live test package is named "livetest", it is accessible as kamaki.clients.
livetest and it is designed to check the actual relation between kamaki and
synnefo services.
Kamaki contains a set of functional tests for *kamaki.clients*, called
"livetest". The term "live" means that the tests are performed against an
on-line functional cloud deployment. The package is accessible as
*kamaki.clients.livetest* .
The livetest suite can be activated with the following option on the configuration file::
The livetest commands can be activated by setting the following option in the
configuration file::
[global]
livetest_cli=livetest
or with this kamaki command::
kamaki config set livetest_cli livetest
$ kamaki config set livetest_cli livetest
In most tests, livetest will run as long as the default cloud is configured
correctly. Some commands, though, need some extra settings related to the cloud
the test is performed against, or the example files used in kamaki.
In most cases, it is enough to have the default cloud configured correctly.
Some commands, though, require some extra settings specific to actual contents
of the cloud or the example files used in kamaki.
Here is a list of settings needed:
......@@ -477,19 +489,19 @@ Here is a list of settings needed:
* for astakos client::
* livetest.astakos_details = <A file with an authentication output>
To create this file, pipeline the output of an authentication command
with the -j option for raw jason output
with the -j option for raw json output
.. code-block:: console
$ kamaki user authenticate -j > astakos.details
* livetest.astakos_name = <The exact "real" name of testing user>
* livetest.astakos_name = <The exact "real" name of the testing user>
* livetest.astakos_id = <The valid unique user id of the testing user>
* for image client:
* livetest.image_details = <A file with the image's metadata>
* livetest.image_details = <A file with the image metadata>
To create this file, pipeline the output of an image metadata command
with the -j option for raw jason output
with the -j option for raw json output
.. code-block:: console
......@@ -501,7 +513,7 @@ Here is a list of settings needed:
* for flavors (part of the compute client):
* livetest.flavor_details = <A file with the flavor details>
To create this file, pipeline the output of a flavor info command
with the -j option for raw jason output
with the -j option for raw json output
.. code-block:: console
......@@ -512,20 +524,20 @@ After setup, kamaki can run all tests::
$ kamaki livetest all
a specific test (e.g., astakos)::
a specific test (e.g., pithos scenario)::
$ kamaki livetest pithos
$ kamaki livetest astakos
or a specific method from a service (e.g., create_server @ cyclades)::
or a specific method from a service (e.g., astakos authenticate)::
$ kamaki livetest cyclades create_server
$ kamaki livetest astakos authenticate
The unit testing system
"""""""""""""""""""""""
Kamaki container a set of finegrained unit tests for the kamaki.clients
package. This set is not used when kamaki is running. Instead, it is aimed to
developers who debug or extent the kamaki clients library. For more
information, check the
developers who debug or extent kamaki. For more information, check the
`Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the
`developers section <developers/extending-clients-api.html>`_.
......@@ -6,8 +6,8 @@ specifications. A detailed list of the command specifications can be found in
`Commands <commands.html>`_ section. This guide covers the generic usage of
both interfaces.
What's more, kamaki offers a clients API that allows the development of
external applications for Synnefo. The clients API is listed in the
What's more, kamaki offers a clients library for the development of external
client applications for Synnefo. The clients library API is detailed in the
`Clients lib <developers/code.html#the-clients-api>`_ section.
Quick Setup
......@@ -34,18 +34,18 @@ for the cloud kamaki should communicate with by default:
Shell vs one-command
--------------------
Kamaki users can access Synnefo services through either the interactive shell
or the one-command behaviors. In practice, both systems rely on the same
or the one-command interface. 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.
In favor of interactive shell behavior:
In favor of interactive shell:
* tab completion for commands (if supported by the user's shell)
* session history with ↑ or ↓ keys (if supported by the user's shell)
* shorter commands with command context switching
* re-run old commands with /history
In favor of one-command behavior:
In favor of one-command:
* can be used along with advanced shell features (pipelines, redirection, etc.)
* can be used in shell scripts
......@@ -64,7 +64,8 @@ To use kamaki as a shell, run:
$ kamaki
* with any kind of '-' prefixed arguments, except '-h', '--help'.
* with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
'- - version'.
.. code-block:: console
:emphasize-lines: 1
......@@ -92,7 +93,7 @@ To use kamaki as an one-command tool, run:
.. code-block:: console
:emphasize-lines: 1
Example 2.3.2: List VMs managed by user
Example 2.3.2: List servers managed by user
$ kamaki server list
......@@ -170,20 +171,20 @@ and of a command in that group (list) are shown.
Options:
- - - -
addr : List the addresses of all network interfaces on a server (VM)
console : Get a VNC console to access an existing server (VM)
addr : List the addresses of all network interfaces on a server (server)
console : Get a VNC console to access an existing server (server)
create : Create a server (aka Virtual Machine)
delete : Delete a server (VM)
firewall: Manage server (VM) firewall profiles for public networks
delete : Delete a server (server)
firewall: Manage server (server) firewall profiles for public networks
ip : Manage floating IPs for the servers
info : Detailed information on a Virtual Machine
list : List Virtual Machines accessible by user
metadata: Manage Server metadata (key:value pairs of server attributes)
reboot : Reboot a server (VM)
rename : Set/update a server (VM) name
shutdown: Shutdown an active server (VM)
start : Start an existing server (VM)
stats : Get server (VM) statistics
reboot : Reboot a server (server)
rename : Set/update a server (server) name
shutdown: Shutdown an active server (server)
start : Start an existing server (server)
stats : Get server (server) statistics
resize : Set a different flavor for an existing server
wait : Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
......@@ -221,7 +222,7 @@ and of a command in that group (list) are shown.
--more output results in pages (-n to set items per page,
default 10)
-n LIMIT, --number LIMIT
limit number of listed VMs
limit number of listed servers
-j, --json show headers in json
.. _using-history-ref:
......@@ -406,7 +407,7 @@ A user might **browse** through different contexts during one session.
[file]: exit
[kamaki]: server
[server]: list
... (VMs listing) ...
... (servers listing) ...
[server]: exit
[kamaki]:
......@@ -424,7 +425,7 @@ from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent.
[kamaki]: file list
... (storage container listing) ...
[kamaki]: server list
... (VMs listing) ...
... (servers listing) ...
[kamaki]:
Using Help
......@@ -559,15 +560,15 @@ top-level commands. Kamaki offers access to top-level commands by using the
[context]: /anothercontext cmd1 cmd2 ... cmdN
An example (4.3.1) that showcases how top-level access improves user experience
is the creation of a VM. A VM is created with the command server-create. This
is the creation of a server. A server is created with the command server-create. This
command is called with three parameters:
* the name of the new VM
* the name of the new server
* the flavor id
* the image id
It is often the case that a user who works in the context command, needs to
create a new VM, but hasn't selected a flavor or an image id, or cannot recall
create a new server, but hasn't selected a flavor or an image id, or cannot recall
the id of that flavor or image. Therefore, it is necessary to list all
available flavors (flavor-list) or images (image-compute-list). Both commands
belong to different contexts.
......@@ -575,7 +576,7 @@ belong to different contexts.
.. code-block:: console
:emphasize-lines: 1
Example 4.3.1: Create a VM from server context
Example 4.3.1: Create a server from server context
[server]: create -h
create <name> <flavor id> <image id> ...
......
......@@ -59,12 +59,12 @@ about_authentication = '\nUser Authentication:\
\n* to set authentication token: /config set cloud.<cloud>.token <token>'
howto_personality = [
'Defines a file to be injected to VMs file system.',
'Defines a file to be injected to virtual servers file system.',
'syntax: PATH,[SERVER_PATH,[OWNER,[GROUP,[MODE]]]]',
' PATH: local file to be injected (relative or absolute)',
' SERVER_PATH: destination location inside server Image',
' OWNER: VMs user id of the remote destination file',
' GROUP: VMs group id or name of the destination file',
' OWNER: virtual servers user id of the remote destination file',
' GROUP: virtual servers group id or name of the destination file',
' MODEL: permition in octal (e.g. 0777 or o+rwx)']
......@@ -146,7 +146,8 @@ class server_list(_init_cyclades, _optional_json, _name_filter, _id_filter):
since=DateArgument(
'show only items since date (\' d/m/Y H:M:S \')',
'--since'),