Commit 28dd8a05 authored by Stavros Sachtouris's avatar Stavros Sachtouris

Update general information and setup instructions

Refs grnet/kamaki#49
parent 19522a57
......@@ -123,13 +123,13 @@ master_doc = 'index'
# General information about the project.
project = u'Kamaki'
copyright = u'2013, GRNET'
copyright = u'2014, GRNET'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.12'
version = '0.13'
# The full version, including alpha/beta/rc tags.
try:
......
......@@ -16,17 +16,15 @@ have it up and running in all platforms running Python 2.6 or 2.7.
Linux and Unix-like environments
--------------------------------
Debian:
^^^^^^^
Debian
^^^^^^
The following steps describe a command-line approach, but any graphic package manager can be used instead.
For Debian 7.0 (wheezy):
* As root, append the following to */etc/apt/sources.list* ::
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 repository is added:
.. code-block:: console
......@@ -35,99 +33,108 @@ The following steps describe a command-line approach, but any graphic package ma
otherwise *apt-get update* will produce GPG warnings.
* Update the Debian sources:
* Update and install:
.. code-block:: console
$ sudo apt-get update
$ sudo apt-get install kamaki
* Install kamaki:
Terminal colors (optional but recommended)
""""""""""""""""""""""""""""""""""""""""""
.. code-block:: console
The "python-ansicolors" package enables colorful terminal outputs.
$ sudo apt-get install kamaki
E.g., in Debian:
Ubuntu
^^^^^^
The following steps describe a command-line approach, but any graphic package
manager can be used instead.
.. code-block:: console
* Let ppa take care of the repository configuration:
$ sudo apt-get install python-ansicolors
.. code-block:: console
After the installation, tell kamaki to use the feature
$ sudo apt-get install python-software-properties
$ sudo add-apt-repository ppa:grnet/synnefo
.. code-block:: console
* Update the Debian sources:
$ kamaki config set colors on
.. code-block:: console
Unit tests (developers)
"""""""""""""""""""""""
$ sudo apt-get update
Install the "python-mock" package to make unit tests work (developers only).
* Install kamaki:
.. code-block:: console
.. code-block:: console
$ sudo apt-get install python-mock
$ sudo apt-get install kamaki
Ubuntu
^^^^^^
Install ansicolors (optional but recommended)
"""""""""""""""""""""""""""""""""""""""""""""
For Ubuntu 12.04 LTS, 12.10 and 13.04:
.. code-block:: console
$ sudo apt-get install python-ansicolors
$ sudo apt-get install python-software-properties
$ sudo add-apt-repository ppa:grnet/synnefo
$ sudo apt-get update
$ sudo apt-get install kamaki
Fedora
^^^^^^
.. _installing-from-pypi-ref:
For Fedora 17:
Installing from pypi
^^^^^^^^^^^^^^^^^^^^
.. code-block:: console
Requirements
""""""""""""
$ cd /etc/yum.repos.d
$ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/Fedora_17/home:GRNET:synnefo.repo
$ yum install kamaki
Essential:
CentOS
^^^^^^
* Python 2.6 or 2.7 [http://www.python.org]
* Python setuptools [http://pypi.python.org/pypi/setuptools]
For CentOS 6:
Optional:
.. code-block:: console
* VirtualEnv (python-virtualenv) [http://www.virtualenv.org]
$ cd /etc/yum.repos.d
$ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/CentOS_CentOS-6/home:GRNET:synnefo.repo
$ yum install kamaki
Setup a virtual enviroment (optional)
"""""""""""""""""""""""""""""""""""""
OpenSUSE
^^^^^^^^
Use virtualenv to setup kamaki and Synnefo services in a sandbox environment.
For OpenSUSE 12.3:
.. code-block:: console
$ virtualenv kamaki-env
$ source kamaki-env/bin/activate
$ zypper ar -f http://download.opensuse.org/repositories/home:/GRNET:/synnefo/openSUSE_12.3/home:GRNET:synnefo.repo
$ zypper in kamaki
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
""""""""""""""
.. _installing-from-pypi-ref:
Installing from pypi
--------------------
Requirements:
* Python 2.7 [http://www.python.org]
* Python setuptools [http://pypi.python.org/pypi/setuptools]
Installation:
.. code-block:: console
$ pip install kamaki
Install ansicolors
""""""""""""""""""
The **ansicolors** package is not required for running kamaki, but it is
recommended as a user experience improvement. In specific, ansicolors
adds colors to kamaki responses.
Optional packages:
The ansicolors package enables terminal output coloring. The mock package
allows unit testing while hacking the code.
.. code-block:: console
$ pip install ansicolors
$ pip install mock
Mac OS X
--------
......@@ -141,29 +148,22 @@ Windows
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:
Requirements
^^^^^^^^^^^^
**Requirements**
* Python 2.7 (`Official versions <http://www.python.org/download>`_)
* 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 setuptools installation.
Install Python
^^^^^^^^^^^^^^
Download and run the Windows installer from
`here <http://www.python.org/download>`_
.. note:: Skip this step if python 2.7 is already installed
Users should pick the installer that fits their windows version and machine
architecture.
Download and run the Windows installer from
`the download page <http://www.python.org/download>`_
pick the one that fits your windows version and architecture.
Add Python to windows path
^^^^^^^^^^^^^^^^^^^^^^^^^^
**Add Python to windows path**
The following will allow users to run Python and Python scripts from command
line.
......@@ -181,20 +181,18 @@ line.
.. warning:: In case of a different version, C:\\Python27 should be replaced
with the actual python path in the system
Install setuptools
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.
.. note:: Skip this step if setuptools are already installed
* Users with 32-bit platforms should download and run the graphic
installer
See `here <http://pypi.python.org/pypi/setuptools>`_ for installation
instructions.
* Users with 64-bit platforms should download the
`ez_setup.py <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_
script and install it from a command shell. In the following example, the
script was downloaded at C:\\Downloads::
.. note:: Users with 64-bit platforms should download the
`ez_setup.py <https://bootstrap.pypa.io/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
......
......@@ -49,8 +49,8 @@ command-line tool for managing a local or remote Synnefo deployment.
* by third-party `Synnefo` deployers for testing and debugging their setup
* as an API library for other components in the Synnefo universe ((`burnin`,
`image-creator`) or external applications
* as an API library for Synnefo-related components (`burnin`, `image-creator`)
or external applications
Community & Support
-------------------
......
Setup
=====
Kamaki is easy to install from the official repository or with the pypi mechanism.
The term "setup" refers to the configuration of kamaki after the
`installation <installation.html>`_.
Quick Setup
-----------
......@@ -9,28 +10,25 @@ Quick Setup
.. 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.
To set up Kamaki for a specific Synnefo deployment, users need an
To set up Kamaki for a specific Synnefo deployment (*cloud*), users need an
**authentication URL** and a **user token**. Users should also pick an alias to
name the cloud configuration. This can be any single word, e.g., "default",
name the cloud configuration. This can be any arbitrary word, e.g., "default",
"mycloud" or whatever suits the user.
.. code-block:: console
$ kamaki config set cloud.<cloud alias>.url <cloud-authentication-URL>
$ kamaki config set cloud.<cloud alias>.token myt0k3n==
$ kamaki config set cloud.CLOUD_NAME.url AUTHENTICATION_URL
$ kamaki config set cloud.CLOUD_NAME.token TOKEN
If only one cloud is configured, it is automatically considered the default.
Otherwise, a default cloud should be specified:
.. code-block:: console
$ kamaki config set default_cloud <cloud alias>
$ kamaki config set default_cloud CLOUD_NAME
The endpoints (URLs) for each service are resolved automatically from a single
URL. This mechanism works for Synnefo v0.14 deployments or later. The
authentication URL is retrieved from the Synnefo Web UI and should be set as
the cloud URL for kamaki. Users of Synnefo clouds >=0.14 are advised against
using any service-specific URLs.
The endpoints (URLs) for each service are resolved automatically from this
single authentication URL (Synnefo clouds v0.14 or later).
SSL Authentication
------------------
......@@ -76,215 +74,195 @@ Kamaki features a mechanism of automatic migration of the configuration file to
the latest version, which involves heuristics for guessing and translating the
file.
Quick migration
^^^^^^^^^^^^^^^
Configuration options
---------------------
The easiest way is to backup and remove the configuration file. The default
configuration file location is '${HOME}/.kamakirc'.
There are two kinds of configuration options:
To reset kamaki, a user needs the authentication URL and TOKEN:
* kamaki-related (global)
interface settings and constants that affect kamaki as an application e.g.,
terminal colors, maximum threads per connection, logging options, default
behavior, etc.
.. code-block:: console
* cloud-related
access settings for one or more clouds. The (authentication) URL and token
settings are mandatory. There are also a few optional settings for
overriding some service-specific operations (e.g., endpoint URLs).
$ kamaki config set cloud.default.url URL
$ kamaki config set cloud.default.token TOKEN
All kamaki-related options default to a set of values. Cloud-related
information does not default to anything and should be provided by the user.
After that, a new configuration file will be created. In most cases, this is
enough, since kamaki automatically sets the correct options for every
functionality.
Options can be set with the `kamaki config` command (suggested) or by editing
the configuration file.
Automatic migration
^^^^^^^^^^^^^^^^^^^
Global options
^^^^^^^^^^^^^^
Another way is to let kamaki change the file automatically. Kamaki always
inspects the configuration file and, if understood as an older version, it
suggests some necessary modifications (user permission is required).
* global.default_cloud CLOUD_NAME
The name of the default cloud to be used. See cloud settings bellow.
On example 2.1 we suggest using the `user info` command to invoke the migration
mechanism.
* global.colors < on | **off** >
enable / disable colors in command line based uis. Requires the ansicolors
optional package, otherwise it is ignored
.. code-block:: console
:emphasize-lines: 1
* global.log_file < path (default: $HOME/.kamaki.log) >
The kamaki log file location
Example 2.1: Convert config file while authenticating user "exampleuser"
* global.log_token < on | **off** >
allow kamaki to log user tokens
$ kamaki user info
Config file format version >= 0.12 is required
Configuration file: "/home/exampleuser/.kamakirc"
but kamaki can fix this:
Calculating changes while preserving information
... rescue global.token => cloud.default.token
... rescue config.cli => global.config_cli
... rescue history.file => global.history_file
... change global.network_cli value: `cyclades` => `network`
... 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
* global.log_data < on | **off** >
allow kamaki to log http data (body)
Kamaki is ready to convert the config file to version 0.12
Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
* global.log_pid < on | **off** >
attach the process name and id that produces each log line. Useful for
resolving race condition problems.
At this point, we should examine the kamaki output. Most options are renamed to
match the latest configuration file version specifications.
* global.history_file < path (default: $HOME/.kamaki.history) >
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
Lets take a look at the discarded options:
* global.history_limit POSSITIVE_INTEGER (default: 0 (unlimited))
the maximum number of lines stored in history. If there is a finite limit,
old lines will be deleted automatically.
* `global.account` and `user.account` are not used since version 0.9
The same is true for the synonyms `store.account` and `pithos.account`.
These options were used to explicitly set a user account or uuid to a
pithos call. In the latest Synnefo version (>= 0.14), these features are
meaningless and therefore omitted.
* global.<command group>_cli <command definition package>
options that help kamaki locate the command definitions for each command
group. Some command groups are defined automatically (can be overridden),
others are optional and are not set by default.
* `global.data_log` option has never been a valid kamaki config option.
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).
The following command groups are defined automatically::
Users should press *y* when they are ready, which will cause the default config
file to be modified.
user, quota, resource, project, membership, file, container, sharer,
group, server, flavor, network, subnet, port, ip, volume, sdnapshot,
image, imagecompute, config, history
.. code-block:: console
:emphasize-lines: 1
The following command groups are optional::
Example 2.2: Rescue misspelled log_data option
service, endpoint, commission
$ kamaki config set log_data on
For example, the "endpoint" commands are defined in the "astakos" package,
but are not enabled by default. To enable them:
In order to convert more files, users may run kamaki with the -c option, which
runs kamaki with a different configuration file (Example 2.3) and apply the
steps described above.
.. code-block:: console
$ kamaki config set endpoint_cli astakos
Using multiple configuration files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Kamaki allows users to pick the configuration file at runtime with the
**- - config** (or **- c**) option
.. code-block:: console
:emphasize-lines: 1
Example 2.3: Use kamaki to update a configuration file called ".myfilerc"
$ kamaki --config CONFIGUDATION_FILE [...]
$ kamaki -c .myfilerc user authenticate
.. note:: Multiple clouds can be configured in the same file (suggested). More
details can be found at the `multiple clouds guide <#multiple-clouds>`_.
Multiple clouds
---------------
Modifying options at runtime
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following refers to users of multiple Synnefo and/or Open Stack
deployments. In the following, a Synnefo (or Open Stack) cloud deployment will
be called **a cloud**.
All kamaki commands can be used with the -o option in order to override
configuration options at runtime. For example:
Multiple clouds can be configured and managed 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.
.. code-block:: console
Once a user has retrieved one URL/token pair per cloud, it is time to assign a
name to each cloud and configure kamaki accordingly.
$ kamaki file list -o global.pithos_container=anothercontainer
For example, let the user have access to two clouds with the following authentication information ::
will invoke *kamaki file list* with the specified options, but the initial
global.pithos_container values will not be modified.
cloud alias: devel
authentication URL: https://devel.example.com/astakos/identity/v2.0/
authentication token: myd3v3170k3n==
Editing options
^^^^^^^^^^^^^^^
cloud alias: testing
autentication URL: https://testing.example.com/astakos/identity/v2.0/
authentication token: my73571ng70k3n==
Use the `kamaki config` commands to control the configuration settings.
.. note:: the cloud alias is arbitrary and decided by the user. It is just a
reference label for the cloud setup in the kamaki context.
* kamaki config list
lists all configuration options
The user should let kamaki know about these setups:
* kamaki config get GROUP
list the options in a group
* kamaki config get [GROUP.]OPTION
show the value of an option. GROUP defaults to "global".
.. code-block:: console
* kamaki config set [GROUP.]OPTION VALUE
set an OPTION to VALUE. GROUP defaults to "global".
$ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/
$ kamaki config set cloud.devel.token myd3v3170k3n==
$
$ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/
$ kamaki config set cloud.testing.token my73571ng70k3n==
$
* kamaki config delete GROUP
delete a whole group of settings
To check if all settings are loaded, a user may list all clouds, as shown
bellow:
* kamaki config delete [GROUP.]OPTION
delete a configuration option. GROUP defaults to "global".
.. code-block:: console
.. note:: The terms "global" and "cloud" are always group names.
$ kamaki config get cloud
cloud.default.url = https://example.com/astakos.identity/v2.0/
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/
cloud.testing.token = my73571ng70k3n==
$
The above commands cause option values to be permanently stored in the Kamaki
configuration file. They can also be used for **cloud** handling, with the
`cloud.` prefix.
or query kamaki for a specific cloud:
* kamaki config get cloud
list all clouds and their settings
.. code-block:: console
* kamaki config get cloud.CLOUD_NAME
list settings of the cloud with CLOUD_NAME. If no
special is configured, use the term `cloud.default`
$ kamaki config get cloud.devel
cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
cloud.devel.token = myd3v3170k3n==
$
* kamaki config get cloud.CLOUD_NAME.OPTION
show the value of an option option
Now kamaki can use any of these clouds, with the **- - cloud** attribute. If
the **- - cloud** option is omitted, kamaki will query the `default` cloud.
* kamaki config set cloud.CLOUD_NAME.OPTION VALUE
Set the value of CLOUD_NAME.OPTION to VALUE
One way to test this, is the `user info` command:
* kamaki config delete cloud.CLOUD_NAME
delete the cloud with CLOUD_NAME and all its options
.. code-block:: console
* kamaki config delete cloud.CLOUD_NAME.OPTION
delete the OPTION and its value from the cloud with CLOUD_NAME
$ kamaki --cloud=devel user info
...
id : 725d5de4-1bab-45ac-9e98-38a60a8c543c
name : Devel User
$
$ kamaki --cloud=testing user info
...
id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83
name : Testing User
$
$ kamaki --cloud=default user info
...
id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
name : Default User
$
$ kamaki user info
...
id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
name : Default User
$
The [global.]default_cloud option is optional, but very useful if there are
more than one clouds configured:
In interactive cell, the cloud option should be passed when calling the shell.
.. code-block:: console
.. code-block:: console
$ kamaki config get default_cloud
$ kamaki config set default_cloud CLOUD_NAME
$ kamaki-shell --cloud=devel
kamaki v0.10 - Interactive Shell
Configuration file
^^^^^^^^^^^^^^^^^^
/exit terminate kamaki
exit or ^D exit context
? or help available commands
?command help on command
!<command> execute OS shell command
The configuration file is a simple text file. Its default location is at
$HOME/.kamakirc
Session user is Devel User
(uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c)
[kamaki]:
To create the configuration file, `setup a cloud <#quick-setup>`_ and the file
will be updated or created at the default location.
The configuration file format is dictated by the python ConfigParser module
with some extentions for handling clouds. An example::
[global]
log_file = /home/exampleuser/logs/kamaki.log
max_threads = 7
colors = off
[cloud "default"]
url = https:://www.example.org/authentication
token = s0m370k3n
Optional features
-----------------
.. note:: Most options do not appear in the file, except to be overridden.
Additional features
^^^^^^^^^^^^^^^^^^^
For installing any or all of the following, consult the
`kamaki installation guide <installation.html#install-ansicolors>`_
`kamaki installation guide <installation.html>`_
* ansicolors
* Add colors to command line / console output
* Can be switched on/off in kamaki configuration file: `colors = on/off`
* Can be switched with global.colors
* Has not been tested on non unix / linux based platforms
* mock
......@@ -295,170 +273,164 @@ For installing any or all of the following, consult the
Any of the above features can be installed at any time before or after kamaki
installation.
Configuration options
---------------------
There are two kinds of configuration options:
Functional tests
""""""""""""""""
* kamaki-related (global)
interface settings and constants of the kamaki internal mechanism, e.g.,
terminal colors, maximum threads per connection, custom logging, history
file path, etc.
Kamaki does not include functional tests in its native code. The synnefo tool
snf-burnin can be used instead.
* cloud-related
information needed to connect and use one or more clouds. There are some
mandatory options (URL, token) and some advanced / optional (e.g.,
service-specific URL overrides or versions)
Unit tests
""""""""""
Kamaki comes with preset default values to all kamaki-related configuration
options. Cloud-related information is not included in presets and should be
provided by the user. Kamaki-related options can also be modified.
Kamaki features a set of 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 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>`_.
There are two ways of managing configuration options: edit the config file or
use the kamaki config command.
Using multiple configuration files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Multiple clouds
---------------
Kamaki setups are stored in configuration files. By default, a Kamaki
installation stores options in *.kamakirc* file located at the user home
directory.
Kamaki can be used to "poke" different Synnefo (or other OpenStack-compatible)
deployments (clouds).
If a user needs to switch between different kamaki-related setups, Kamaki can
explicitly load configuration files with the **- - config** (or **- c**) option
Multiple clouds can be configured and managed in a single kamaki setup. Each
cloud is configured through a single point of authentication (an
**authentication URL** and **token** pair). Users can retrieve this information
through the cloud UI.
.. code-block:: console
For example, let the user have access to two clouds with the following
authentication information ::
$ kamaki --config <custom_config_file_path> [other options]
cloud name: devel
authentication URL: https://devel.example.com/astakos/identity/v2.0/
authentication token: myd3v3170k3n==
.. note:: For accessing multiple clouds, users do NOT need to create multiple
configuration files. Instead, we suggest using a single configuration file
with multiple cloud setups. More details can be found at the
`multiple clouds guide <#multiple-clouds>`_.
cloud name: testing
autentication URL: https://testing.example.com/astakos/identity/v2.0/
authentication token: my73571ng70k3n==
Modifying options at runtime
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: the cloud names are arbitrary and decided by the user