Revision fa479dc3

b/docs/installation.rst
1 1
Installation
2 2
============
3 3

  
4
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.
4
This guide describes the standard installation process for kamaki, with the
5
aspiration of covering as much cases as possible. Although kamaki was initially
6
targeted to Linux/Unix-like users, it is quite straightforward to install and
7
have it up and running in all platforms running python 2.6 or 2.7.
5 8

  
6 9

  
7 10
* Kamaki repository: `http://code.grnet.gr/git/kamaki <http://code.grnet.gr/git/kamaki>`_
8 11

  
9 12
* Kamaki at pypi: `http://pypi.python.org/pypi/kamaki <https://pypi.python.org/pypi/kamaki>`_
10 13

  
11
* Synnefo Linux packages: `http://apt2.dev.grnet.gr <http://apt2.dev.grnet.gr>`_
14
* Synnefo Linux packages: `http://apt.dev.grnet.gr <http://apt.dev.grnet.gr>`_
12 15

  
13 16
Linux and Unix-like enviroments
14 17
-------------------------------
......
20 23

  
21 24
* As root, append the following to */etc/apt/sources.list* ::
22 25

  
23
    deb http://apt2.dev.grnet.gr stable/
26
    deb http://apt.dev.grnet.gr wheezy/
27

  
28
.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze"
24 29

  
25 30
* Make sure the GPG public key for the Synnefo development team is added:
26 31

  
......
94 99

  
95 100
Essential:
96 101

  
97
 * Python 2.6 or better [http://www.python.org]
102
 * Python 2.6 or 2.7 [http://www.python.org]
98 103
 * Python setuptools [http://pypi.python.org/pypi/setuptools]
99 104

  
100 105
Optional:
......
104 109
Setup a virtual enviroment (optional)
105 110
"""""""""""""""""""""""""""""""""""""
106 111

  
107
With virtualenv users can setup kamaki and synnefo services in a sandbox environment.
112
With virtualenv users can setup kamaki and synnefo services in a sandbox
113
environment.
108 114

  
109 115
.. code-block:: console
110 116

  
111 117
    $ virtualenv kamaki-env
112 118
    $ source kamaki-env/bin/activate
113 119

  
114
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>`_
120
A more detailed example of using virtual env can be found at the 
121
`snf-image-creator setup guide <http://www.synnefo.org/docs/snf-image-creator/latest/install.html#python-virtual-environment>`_
115 122

  
116 123
Install kamaki
117 124
""""""""""""""
......
120 127

  
121 128
    $ pip install kamaki
122 129

  
123
Install ansicolors
124
""""""""""""""""""
130
Install ansicolors (optional)
131
"""""""""""""""""""""""""""""
125 132

  
126 133
The **ansicolors** package is not required for running kamaki, but it is
127 134
recommended as a user experience improvement. In specific, ansicolors
......
131 138

  
132 139
    $ pip install ansicolors
133 140

  
134
Install mock
135
""""""""""""
141
Install mock (developers only)
142
""""""""""""""""""""""""""""""
136 143

  
137
The **mock** package is needed for running the prepared unit-tests in the kamaki.clients
138
package. This feature is useful when extendnig / debugging kamaki functionality and is
139
aimed to kamaki developers and contributors. Therefore, users can enjoy the full kamaki
140
user experience without installing mock.
144
The **mock** package is needed for running the prepared unit-tests in the
145
kamaki.clients package. This feature is useful when extending / debugging
146
kamaki functionality and is aimed to kamaki developers and contributors.
147
Therefore, users can enjoy the full kamaki user experience without installing
148
mock.
141 149

  
142 150
.. code-block:: console
143 151

  
......
148 156
Mac OS X
149 157
--------
150 158

  
151
Kamaki can be installed on Mac OS X systems from source, by following the steps at :ref:`installing-from-pypi-ref`.
159
Kamaki can be installed on Mac OS X systems from source, by following the steps
160
at :ref:`installing-from-pypi-ref`.
152 161

  
153 162
Windows
154 163
-------
155 164

  
156
Kamaki can be installed on Windows by following the pypi method. Installing the requirements is a bit different than in other systems. 
165
Kamaki can be installed on Windows by following the pypi method. Installing the
166
requirements is a bit different than in other systems. 
157 167

  
158 168
The full process is detailed in the following:
159 169

  
......
164 174

  
165 175
* Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
166 176

  
167
Users who have already set up python and setuptools (e.g. for another project) may skip python and / or setup tools installation.
177
Users who have already set up and wokring python and setuptools (e.g. for
178
another project) may skip python and / or setup tools installation.
168 179

  
169 180
Install python
170 181
^^^^^^^^^^^^^^
171 182

  
172
Download and run the Windows installer from `here <http://www.python.org/getit>`_
183
Download and run the Windows installer from
184
`here <http://www.python.org/getit>`_
173 185

  
174
Users should pick the installer that fits their windows version and architecture.
186
Users should pick the installer that fits their windows version and machine
187
architecture.
175 188

  
176 189
Add python to windows path
177 190
^^^^^^^^^^^^^^^^^^^^^^^^^^
178 191

  
179
The following will allow users to run python and python scripts from command line.
192
The following will allow users to run python and python scripts from command
193
line.
180 194

  
181
* Select **System** from the Control Panel, select the **Advanced** tab, the **Environment Variables** button and then find the **PATH** (user or system) and **edit**
195
* Select **System** from the Control Panel, select the **Advanced** tab, the
196
    **Environment Variables** button and then find the **PATH** (user or
197
    system) and **edit**
182 198

  
183 199
* Without removing existing values, append the following to PATH::
184 200

  
185
    C:\Python;C:\Python\Scripts
201
    ;C:\Python27;C:\Python27\Scripts
186 202

  
187 203
.. note:: Path values are separated by semicolons
188 204

  
189
.. warning:: C:\\Python should be replaced with the actual python path in the system, e.g. C:\\Python27
205
.. warning:: In case of a different version, C:\\Python27 should be replaced
206
    with the actual python path in the system
190 207

  
191 208
Install setuptools
192 209
^^^^^^^^^^^^^^^^^^
193 210

  
194
According to the corresponding `python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools installer doesn't currently work on 64bit machines.
211
According to the corresponding
212
`python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools
213
installer doesn't currently work on 64bit machines.
195 214

  
196
* Users with 32-bit operating systems should download and run the graphic installer
215
* Users with 32-bit operating systems should download and run the graphic
216
    installer
197 217

  
198
* 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::
218
* Users with 64-bit machines should download the
219
    `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_ script and
220
    install it from a command shell. In the following example, the script was
221
    downloaded at C:\\Downloads::
199 222

  
200
    C:\> cd Downloads
201
    C:\Downloads\> python ez_setup.py
202
    ...
203
    Installation finished
204
    C:\Downloads\>
223
        C:\> cd Downloads
224
        C:\Downloads\> python ez_setup.py
225
        ...
226
        Installation finished
227
        C:\Downloads\>
205 228

  
206 229
Install kamaki
207 230
^^^^^^^^^^^^^^
208 231

  
209 232
.. code-block:: console
210 233

  
211
    $ easy_setup kamaki
234
    $ easy_install kamaki
b/docs/overview.rst
4 4
History
5 5
-------
6 6

  
7
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.
8

  
9
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.
10

  
11
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.
7
Kamaki was created on 2011 by the Synnefo (http://www.synnefo.org) development
8
team of the *Greek Research and Technology Network (GRNET)*, initially as an
9
internal project and later as a multipurpose tool for all users.
10

  
11
Synnefo is an IaaS system which is based on and extents OpenStack.
12
Synnefo has been deployed in many environments to cover multiple needs. The
13
most notable, deployment is probably the GRNET's
14
`~okeanos <http://okeanos.grnet.gr>`_ IaaS service, running in GRNET data
15
centers, is used to offer cloud services to the Greek Research and Academic
16
Community.
17

  
18
Kamaki was originally conceived as a handy tool for the developers of *Synnefo*
19
and the administrators of *Okeanos*. The initial purpose of kamaki was to
20
provide an easy to use command line client for accessing the various ReST APIs
21
of Synnefo.
22

  
23
Kamaki has been designed to act as a command line client as well as a python
24
library for client developers. It is widely used in various synnefo and okeanos
25
components. Third parties are also encouraged to use the kamaki library for
26
developing their own python-based cloud-client applications.
27

  
28
As Synnefo became a full, scalable and stable cloud solution, kamaki also
29
evolved to an intuitive, multipurpose tool, available to a wider user base.
30
For example, it is used as the main Pithos+ client at Linux and other Unix-like
31
environments. It can be easily set up in all popular platforms, including
32
recent Linux, OS X and Windows releases.
12 33

  
13 34
Who uses *kamaki*?
14 35
------------------
15 36

  
16
Kamaki is targeted to new and advanced users who need an intuitive managerial console tool to manage a local or remote synnefo cloud installation.
37
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
38
excluding users who need to use just parts of the cloud system (e.g. only
39
Pihtos+ storage service or only Image services)
40

  
41
*kamaki* is currently used
17 42

  
18
*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.
43
* internally by the Synnefo development team to test the synnefo software,
19 44

  
20
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).
45
* by the deployment team which operates the GRNET ~okeanos service
21 46

  
47
* as the main Pithos+ client at Linux and other Unix-like environments
48

  
49
* by third party Synnefo deploys who need to test and debug their cloud setup
50

  
51
* as an API library for other components in the Synnefo universe.
22 52

  
23 53
Contributing and helping out
24 54
----------------------------
25 55

  
26
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.
27

  
56
The *kamaki* development team values your help and depends on community feedback for feature evolution. Any contributions and bug reports will be
57
highly appreciated.
28 58

  
29 59
Community & Support
30 60
-------------------
b/docs/setup.rst
1 1
Setup
2 2
=====
3 3

  
4
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.
4
Kamaki is easy to install from source or as a package. Some advanced or ui features
5
are optional and can be installed separately. Kamaki behavior can be configured in
6
the kamaki config file.
5 7

  
6 8
Quick Setup
7 9
-----------
8 10

  
9
Kamaki interfaces rely on a list of configuration options. Be default, they are configured to communicate with the `Okeanos IaaS <http://okeanos.grnet.gr>`_.
11
Existing kamaki users should consult the
12
`migration guide <#migrating-from-kamaki-0-8-x-to-0-9>`_ first.
10 13

  
11
.. 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:
14
Kamaki has to be configured to use a specific Synnefo deployment.
12 15

  
16
Since Synnefo version 0.14, each deployment offers a single authentication
17
url, which has to be set as the default url for kamaki (Example 1.1).
18

  
19
.. code-block:: console
20
    :emphasize-lines: 1, 2
21

  
22
    Example 1.1: Set https://astakos.example.com/astakos/identity/v2.0/ as the
23
    default single authentication url 
24
    
25
    $ kamaki config set remote.default.url https://astakos.example.com/astakos/identity/v2.0/
26

  
27
Kamaki also needs a user authentication token (Example 1.2).
28

  
29
.. code-block:: console
30
    :emphasize-lines: 1
31

  
32
    Example 1.2: Set user token to myt0k3n==
33

  
34
    $ kamaki config set remote.default.token myt0k3n==
35

  
36
Migrating from kamaki 0.8.X to 0.9
37
----------------------------------
38

  
39
This section refers to running installations of kamaki version <= 0.8.X
40
To check the current kamaki version:
41

  
42
.. code-block:: console
43

  
44
    $ kamaki -V
45

  
46
Existing kamaki users should convert their configuration files to v3. To do
47
that, kamaki 0.9 inspects the configuration file and suggests a list of config
48
file transformations, which are performed automatically on user permission.
49
This mechanism is invoked when the first API-releated kamaki command is fired.
50
We suggest the command of the example 2.1.
51

  
52
.. code-block:: console
53
    :emphasize-lines: 1
54

  
55
    Example 2.1: Try to authenticate user but convert config file instead
56

  
57
    $ kamaki user authenticate
58
    Config file format version >= 3.0 is required
59
    Configuration file "/home/exampleuser/.kamakirc" format is not up to date
60
    but kamaki can fix this:
61
    Calculating changes while preserving information
62
    ... rescue global.token => remote.default.token
63
    ... rescue config.cli => global.config_cli
64
    ... rescue history.file => global.history_file
65
    ... DONE
66
    The following information will NOT be preserved:
67
        global.account = 
68
        global.data_log = on
69
        user.account = exampleuser@example.com
70
        user.url = https://accounts.okeanos.grnet.gr
71
        compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1
72
        file.url = https://pithos.okeanos.grnet.gr/v1
73
        image.url = https://cyclades.okeanos.grnet.gr/plankton
74

  
75
    Kamaki is ready to convert the config file to version 3.0
76
    Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
77

  
78
At this point, we should examine the kamaki output. Most options are renamed to
79
be accessible by the new kamaki.
80

  
81
Let's take a look at the discarded options:
82

  
83
* global.account and user.account are not used anymore. The same is true for
84
    store.account and pithos.account which were ways to explicitly set a user
85
    account name to a pithos call. After the latest Synnefo evolutions, these
86
    features are meaningless and therefore omitted.
87

  
88
* global.data_log option has never been a valid kamaki config option. In this
89
    example, the user accidentally mixed the terms "log_data" (which is a valid
90
    kamaki config option) with "data_log". To fix this, the user should set the
91
    correct option after the conversion is complete (Example 2.2)
92

  
93
Users should press *y* when they are ready. Kamaki has now modified the default
94
config file to conform with kamaki config file v3. Now users should rescue
95
unrescued information (if any).
96

  
97
.. code-block:: console
98
    :emphasize-lines: 1
99

  
100
    Example 2.2: Rescue misspelled log_data option
101

  
102
    $ kamaki config set log_data on
103

  
104
In order to convert more files, users may run kamaki with the -c option
105
(Example 2.3) and apply the steps described above.
13 106

  
14 107
.. code-block:: console
15 108
    :emphasize-lines: 1
16 109

  
17
    Example 1.1: Set user token to myt0k3n==
110
    Example 2.3: Use kamaki to update a configuration file called ".myfilerc"
18 111

  
19
    $ kamaki config set token myt0k3n==
112
    $ kamaki -c .myfilerc user authenticate
20 113

  
21 114
Optional features
22 115
-----------------
23 116

  
24
For installing any or all of the following, consult the `kamaki installation guide <installation.html#install-ansicolors>`_
117
For installing any or all of the following, consult the
118
`kamaki installation guide <installation.html#install-ansicolors>`_
25 119

  
26 120
* ansicolors
27 121
    * Make command line / console user interface responses prettier with text formating (colors, bold, etc.)
b/kamaki/cli/config.py
187 187
                        print('... rescue %s.%s => global.%s_cli' % (
188 188
                            s, k, trn['cmd']))
189 189
                        self.set('global', 'file_cli', v)
190
                    elif v and k in ('url', 'token'):
191
                        print(
192
                            '... rescue %s.%s => remote.default.%s_%s' % (
193
                                s, k, trn['serv'], k))
194
                        self.set_remote('default', 'pithos_%s' % k, v)
195 190
                    elif (k in ('container', 'uuid')) and (
196 191
                            trn['serv'] in ('pithos',)):
197 192
                        print(

Also available in: Unified diff