Installation
============
-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.
+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 Linux/Unix-like users, it is quite straightforward to install and
+have it up and running in all platforms running python 2.6 or 2.7.
* Kamaki repository: `http://code.grnet.gr/git/kamaki <http://code.grnet.gr/git/kamaki>`_
* Kamaki at pypi: `http://pypi.python.org/pypi/kamaki <https://pypi.python.org/pypi/kamaki>`_
-* Synnefo Linux packages: `http://apt2.dev.grnet.gr <http://apt2.dev.grnet.gr>`_
+* Synnefo Linux packages: `http://apt.dev.grnet.gr <http://apt.dev.grnet.gr>`_
Linux and Unix-like enviroments
-------------------------------
* As root, append the following to */etc/apt/sources.list* ::
- deb http://apt2.dev.grnet.gr stable/
+ deb http://apt.dev.grnet.gr wheezy/
+
+.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze"
* Make sure the GPG public key for the Synnefo development team is added:
Essential:
- * Python 2.6 or better [http://www.python.org]
+ * Python 2.6 or 2.7 [http://www.python.org]
* Python setuptools [http://pypi.python.org/pypi/setuptools]
Optional:
Setup a virtual enviroment (optional)
"""""""""""""""""""""""""""""""""""""
-With virtualenv users can setup kamaki and synnefo services in a sandbox environment.
+With virtualenv users can setup kamaki and synnefo services in a sandbox
+environment.
.. code-block:: console
$ virtualenv kamaki-env
$ source kamaki-env/bin/activate
-A more detailed example of using virtual env can be found at the `snf-image-creator setup guide <http://www.synnefo.org/docs/snf-image-creator/latest/install.html#python-virtual-environment>`_
+A more detailed example of using virtual env can be found at the
+`snf-image-creator setup guide <http://www.synnefo.org/docs/snf-image-creator/latest/install.html#python-virtual-environment>`_
Install kamaki
""""""""""""""
$ pip install kamaki
-Install ansicolors
-""""""""""""""""""
+Install ansicolors (optional)
+"""""""""""""""""""""""""""""
The **ansicolors** package is not required for running kamaki, but it is
recommended as a user experience improvement. In specific, ansicolors
$ pip install ansicolors
-Install mock
-""""""""""""
+Install mock (developers only)
+""""""""""""""""""""""""""""""
-The **mock** package is needed for running the prepared unit-tests in the kamaki.clients
-package. This feature is useful when extendnig / debugging kamaki functionality and is
-aimed to kamaki developers and contributors. Therefore, users can enjoy the full kamaki
-user experience without installing mock.
+The **mock** package is needed for running the prepared unit-tests in the
+kamaki.clients package. This feature is useful when extending / debugging
+kamaki functionality and is aimed to kamaki developers and contributors.
+Therefore, users can enjoy the full kamaki user experience without installing
+mock.
.. code-block:: console
Mac OS X
--------
-Kamaki can be installed on Mac OS X systems from source, by following the steps at :ref:`installing-from-pypi-ref`.
+Kamaki can be installed on Mac OS X systems from source, by following the steps
+at :ref:`installing-from-pypi-ref`.
Windows
-------
-Kamaki can be installed on Windows by following the pypi method. Installing the requirements is a bit different than in other systems.
+Kamaki can be installed on Windows by following the pypi method. Installing the
+requirements is a bit different than in other systems.
The full process is detailed in the following:
* Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
-Users who have already set up python and setuptools (e.g. for another project) may skip python and / or setup tools installation.
+Users who have already set up and wokring python and setuptools (e.g. for
+another project) may skip python and / or setup tools installation.
Install python
^^^^^^^^^^^^^^
-Download and run the Windows installer from `here <http://www.python.org/getit>`_
+Download and run the Windows installer from
+`here <http://www.python.org/getit>`_
-Users should pick the installer that fits their windows version and architecture.
+Users should pick the installer that fits their windows version and machine
+architecture.
Add python to windows path
^^^^^^^^^^^^^^^^^^^^^^^^^^
-The following will allow users to run python and python scripts from command line.
+The following will allow users to run python and python scripts from command
+line.
-* Select **System** from the Control Panel, select the **Advanced** tab, the **Environment Variables** button and then find the **PATH** (user or system) and **edit**
+* Select **System** from the Control Panel, select the **Advanced** tab, the
+ **Environment Variables** button and then find the **PATH** (user or
+ system) and **edit**
* Without removing existing values, append the following to PATH::
- C:\Python;C:\Python\Scripts
+ ;C:\Python27;C:\Python27\Scripts
.. note:: Path values are separated by semicolons
-.. warning:: C:\\Python should be replaced with the actual python path in the system, e.g. C:\\Python27
+.. warning:: In case of a different version, C:\\Python27 should be replaced
+ with the actual python path in the system
Install setuptools
^^^^^^^^^^^^^^^^^^
-According to the corresponding `python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools installer doesn't currently work on 64bit machines.
+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 installer
+* Users with 32-bit operating systems should download and run the graphic
+ installer
-* Users with 64-bit machines 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::
+* Users with 64-bit machines 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::
- C:\> cd Downloads
- C:\Downloads\> python ez_setup.py
- ...
- Installation finished
- C:\Downloads\>
+ C:\> cd Downloads
+ C:\Downloads\> python ez_setup.py
+ ...
+ Installation finished
+ C:\Downloads\>
Install kamaki
^^^^^^^^^^^^^^
.. code-block:: console
- $ easy_setup kamaki
+ $ easy_install kamaki
History
-------
-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.
-
-From the early start, we needed a simple command-line tool to test the OpenStack API. That's why we developed *kamaki*, which proved to be powerful and intuitive enough, to be used not only for testing purposes but also as a complete Openstack Compute API v1.1 client, able to manage our cloud from the command line.
-
-Once it proved so useful to us, we decided to open the source, so the community can benefit from it, and *kamaki* can benefit from the community too.
+Kamaki was created on 2011 by the Synnefo (http://www.synnefo.org) development
+team of the *Greek Research and Technology Network (GRNET)*, initially as an
+internal project and later as a multipurpose tool for all users.
+
+Synnefo is an IaaS system which is based on and extents OpenStack.
+Synnefo has been deployed in many environments to cover multiple needs. The
+most notable, deployment is probably the GRNET's
+`~okeanos <http://okeanos.grnet.gr>`_ IaaS service, running in GRNET data
+centers, is used to offer cloud services to the Greek Research and Academic
+Community.
+
+Kamaki was originally conceived as a handy tool for the developers of *Synnefo*
+and the administrators of *Okeanos*. The initial purpose of kamaki was to
+provide an easy to use command line client for accessing the various ReST APIs
+of Synnefo.
+
+Kamaki has been designed to act as a command line client as well as a python
+library for client developers. It is widely used in various synnefo and okeanos
+components. Third parties are also encouraged to use the kamaki library for
+developing their own python-based cloud-client applications.
+
+As Synnefo became a full, scalable and stable cloud solution, kamaki also
+evolved to an intuitive, multipurpose tool, available to a wider user base.
+For example, it is used as the main Pithos+ client at Linux and other Unix-like
+environments. It can be easily set up in all popular platforms, including
+recent Linux, OS X and Windows releases.
Who uses *kamaki*?
------------------
-Kamaki is targeted to new and advanced users who need an intuitive managerial console tool to manage a local or remote synnefo cloud installation.
+Kamaki is targeted to new and advanced users who need an intuitive managerial console tool to manage a local or remote synnefo cloud installation, without
+excluding users who need to use just parts of the cloud system (e.g. only
+Pihtos+ storage service or only Image services)
+
+*kamaki* is currently used
-*kamaki* is currently used (i) internally by the Synnefo development team to test the synnefo software, (ii) by the deployment team which operates the GRNET ~okeanos service and (iii) by the testers using the ~okeanos service or other synnefo installations and want to access the services from command line.
+* internally by the Synnefo development team to test the synnefo software,
-What's more, (iv) *kamaki* clients API is used in synnefo as an API for accessing remote services as well as (v) for building manager tools of various synnefo functions (e.g. image registration).
+* by the deployment team which operates the GRNET ~okeanos service
+* as the main Pithos+ client at Linux and other Unix-like environments
+
+* by third party Synnefo deploys who need to test and debug their cloud setup
+
+* as an API library for other components in the Synnefo universe.
Contributing and helping out
----------------------------
-The *kamaki* development team values your help and depends on community feedback for feature evolution. Any contributions and bug reports will be highly appreciated. Using *kamaki* and sending us feedback is also a good start.
-
+The *kamaki* development team values your help and depends on community feedback for feature evolution. Any contributions and bug reports will be
+highly appreciated.
Community & Support
-------------------
Setup
=====
-Kamaki is easy to install from source or as a package. Some ui features are optional and can be install separately. Kamaki behavior can be configured in the kamaki config file.
+Kamaki is easy to install from source or as a package. Some advanced or ui features
+are optional and can be installed separately. Kamaki behavior can be configured in
+the kamaki config file.
Quick Setup
-----------
-Kamaki interfaces rely on a list of configuration options. Be default, they are configured to communicate with the `Okeanos IaaS <http://okeanos.grnet.gr>`_.
+Existing kamaki users should consult the
+`migration guide <#migrating-from-kamaki-0-8-x-to-0-9>`_ first.
-.. note:: It is essential for users to get a configuration token (okeanos.grnet.gr users go `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
+Kamaki has to be configured to use a specific Synnefo deployment.
+Since Synnefo version 0.14, each deployment offers a single authentication
+url, which has to be set as the default url for kamaki (Example 1.1).
+
+.. code-block:: console
+ :emphasize-lines: 1, 2
+
+ Example 1.1: Set https://astakos.example.com/astakos/identity/v2.0/ as the
+ default single authentication url
+
+ $ kamaki config set remote.default.url https://astakos.example.com/astakos/identity/v2.0/
+
+Kamaki also needs a user authentication token (Example 1.2).
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 1.2: Set user token to myt0k3n==
+
+ $ kamaki config set remote.default.token myt0k3n==
+
+Migrating from kamaki 0.8.X to 0.9
+----------------------------------
+
+This section refers to running installations of kamaki version <= 0.8.X
+To check the current kamaki version:
+
+.. code-block:: console
+
+ $ kamaki -V
+
+Existing kamaki users should convert their configuration files to v3. To do
+that, kamaki 0.9 inspects the configuration file and suggests a list of config
+file transformations, which are performed automatically on user permission.
+This mechanism is invoked when the first API-releated kamaki command is fired.
+We suggest the command of the example 2.1.
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 2.1: Try to authenticate user but convert config file instead
+
+ $ kamaki user authenticate
+ Config file format version >= 3.0 is required
+ Configuration file "/home/exampleuser/.kamakirc" format is not up to date
+ but kamaki can fix this:
+ Calculating changes while preserving information
+ ... rescue global.token => remote.default.token
+ ... rescue config.cli => global.config_cli
+ ... rescue history.file => global.history_file
+ ... DONE
+ The following information will NOT be preserved:
+ global.account =
+ global.data_log = on
+ user.account = exampleuser@example.com
+ user.url = https://accounts.okeanos.grnet.gr
+ compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1
+ file.url = https://pithos.okeanos.grnet.gr/v1
+ image.url = https://cyclades.okeanos.grnet.gr/plankton
+
+ Kamaki is ready to convert the config file to version 3.0
+ Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
+
+At this point, we should examine the kamaki output. Most options are renamed to
+be accessible by the new kamaki.
+
+Let's take a look at the discarded options:
+
+* global.account and user.account are not used anymore. The same is true for
+ store.account and pithos.account which were ways to explicitly set a user
+ account name to a pithos call. After the latest Synnefo evolutions, these
+ features are meaningless and therefore omitted.
+
+* global.data_log option has never been a valid kamaki config option. In this
+ example, the user accidentally mixed the terms "log_data" (which is a valid
+ kamaki config option) with "data_log". To fix this, the user should 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).
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 2.2: Rescue misspelled log_data option
+
+ $ kamaki config set log_data on
+
+In order to convert more files, users may run kamaki with the -c option
+(Example 2.3) and apply the steps described above.
.. code-block:: console
:emphasize-lines: 1
- Example 1.1: Set user token to myt0k3n==
+ Example 2.3: Use kamaki to update a configuration file called ".myfilerc"
- $ kamaki config set token myt0k3n==
+ $ kamaki -c .myfilerc user authenticate
Optional features
-----------------
-For installing any or all of the following, consult the `kamaki installation guide <installation.html#install-ansicolors>`_
+For installing any or all of the following, consult the
+`kamaki installation guide <installation.html#install-ansicolors>`_
* ansicolors
* Make command line / console user interface responses prettier with text formating (colors, bold, etc.)
print('... rescue %s.%s => global.%s_cli' % (
s, k, trn['cmd']))
self.set('global', 'file_cli', v)
- elif v and k in ('url', 'token'):
- print(
- '... rescue %s.%s => remote.default.%s_%s' % (
- s, k, trn['serv'], k))
- self.set_remote('default', 'pithos_%s' % k, v)
elif (k in ('container', 'uuid')) and (
trn['serv'] in ('pithos',)):
print(
projects / kamaki / commitdiff