Statistics
| Branch: | Tag: | Revision:

root / docs / setup.rst @ 4054c46d

History | View | Annotate | Download (11.2 kB)

1
Setup
2
=====
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.
5

    
6
Quick Setup
7
-----------
8

    
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>`_.
10

    
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:
12

    
13

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

    
17
    Example 1.1: Set user token to myt0k3n==
18

    
19
    $ kamaki set token myt0k3n==
20

    
21
Optional features
22
-----------------
23

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

    
26
* ansicolors
27
    * Make command line / console user interface responses prettier with text formating (colors, bold, etc.)
28
    * Can be switched on/off in kamaki configuration file: colors=on/off
29
    * Has not been tested on non unix / linux based platforms
30

    
31
* mock 
32
    * For kamaki contributors only
33
    * Allow unittests to run on kamaki.clients package
34
    * Needs mock version 1.X or better
35

    
36
Any of the above features can be installed at any time before or after kamaki installation.
37

    
38
Configuration options
39
---------------------
40

    
41
Kamaki comes with preset default values to all configuration options. All vital configuration options are set to use the okeanos.grnet.gr cloud services. User information is not included and should be provided either through the kamaki config command or by editing the configuration file.
42

    
43
Kamaki configuration options are vital for correct Kamaki behavior. An incorrect option may render some command groups dysfunctional. There are two ways of managing configuration options: edit the config file or use the kamaki config command.
44

    
45
Using multiple setups
46
^^^^^^^^^^^^^^^^^^^^^
47

    
48
Kamaki setups are stored in configuration files. By default, a Kamaki installation stores options in *.kamakirc* file located at the user home directory.
49

    
50
If a user needs to switch between different setups, Kamaki can explicitly load configuration files with the --config option:
51

    
52
.. code-block:: console
53

    
54
    $ kamaki --config <custom_config_file_path> [other options]
55

    
56
Using many different configuration files for different cloud services is encouraged.
57

    
58
Modifying options at runtime
59
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
60

    
61
All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
62

    
63
.. code-block:: console
64

    
65
    $ kamaki store list -o global.account=anotheraccount -o global.token=aT0k3n==
66

    
67
will invoke *kamaki store list* with the specified options, but the initial global.account and global.token values will be restored to initial values afterwards.
68

    
69
.. note:: on-the-fly calls to store require users to explicetely provide the account uuid corresponding to this token. The account is actually the uuid field at the response of the following call::
70

    
71
    $kamaki astakos authenticate aT0k3n==
72

    
73
Editing options
74
^^^^^^^^^^^^^^^
75

    
76
Kamaki config command allows users to see and manage all configuration options.
77

    
78
* kamaki config list
79
    lists all configuration options currently used by a Kamaki installation
80

    
81
* kamaki config get <group.option>
82
    show the value of a specific configuration option. Options must be of the form group.option
83

    
84
* kamaki config set <group.option> <value>
85
    set the group.option to value
86

    
87
* kamaki config delete <group.option>
88
    delete a configuration option
89

    
90
The above commands cause option values to be permanently stored in the Kamaki configuration file.
91

    
92
Editing the configuration file
93
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
94

    
95
The configuration file is a simple text file that can be created by the user.
96

    
97
A simple way to create the configuration file is to set a configuration option using the kamaki config command. For example:
98

    
99
.. code-block:: console
100

    
101
    $ kamaki config set token myT0k3N==
102

    
103
In the above example, if the kamaki configuration file does not exist, it will be created with all the default values plus the *global.token* option set to *myT0k3n==* value.
104

    
105
The configuration file is formatted so that it can be parsed by the python ConfigParser module. It consists of command sections that are denoted with brackets. Every section contains variables with values. For example::
106

    
107
    [store]
108
    url=https://okeanos.grnet.gr/pithos
109
    token=my0th3rT0k3n==
110

    
111
two configuration options are created: *store.url* and *store.token*. These values will be loaded at every future kamaki execution.
112

    
113
Available options
114
^^^^^^^^^^^^^^^^^
115

    
116
The [global] group is treated by kamaki as a generic group for arbitrary options, and it is used as a super-group for vital Kamaki options, namely token, url, cli. In case of conflict, the most specific options overrides the global ones.
117

    
118
* global.colors <on|off>
119
    enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored
120

    
121
* global.token <user authentication token>
122

    
123
* store.cli <UI command specifications for store>
124
    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.
125

    
126
* store.url <OOS storage or Pithos+ service url>
127
    the url of the OOS storage or Pithos+ service. Set to Okeanos.grnet.gr Pithos+ storage service by default. Users should set a different value if they need to use a different storage service.
128

    
129
* store.token <token>
130
    it set, it overrides possible global.token option for store level commands
131

    
132
* compute.url <OOS compute or Cyclades service url>
133
    the url of the OOS compute or Cyclades service. Set to Okeanos.grnet.gr Cyclades IaaS service by default. Users should set a different value if they need to use a different IaaS service.
134

    
135
* cyclades.cli <UI command specifications for cyclades>
136
    a special package that is used to load cyclades commands to kamaki UIs. Don't touch this unless you know what you are doing.
137

    
138
* flavor.cli <UI command specifications for VM flavors>
139
    a special package that is used to load cyclades VM flavor commands to kamaki UIs. Don't touch this unless you know what you are doing.
140

    
141
* network.cli <UI command specifications for virtual networks>
142
    a special package that is used to load cyclades virtual network commands to kamaki UIs. Don't touch this unless you know what you are doing.
143

    
144
* image.url <Plankton image service url>
145
    the url of the Plankton service. Set to Okeanos.grnet.gr Plankton service be default. Users should set a different value if they need to use a different service.
146

    
147
* image.cli <UI command specifications for Plankton and Cyclades image service>
148
    a special package that is used to load image-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
149

    
150
* astakos.url <Astakos authentication service url>
151
    the url of the Astakos authentication service. Set to the Okeanos.grnet.gr Astakos service by default. Users should set a different value if they need to use a different service.
152

    
153
* astakos.cli <UI command specifications for Astakos authentication service>
154
    a special package that is used to load astakos-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
155

    
156
* history.file <history file path>
157
    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
158

    
159
Hidden features
160
^^^^^^^^^^^^^^^
161

    
162
The livetest suite
163
""""""""""""""""""
164

    
165
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.
166

    
167
The livetest suite can be activated with the following option on the configuration file::
168

    
169
    [livetest]
170
    cli=livetest_cli
171

    
172
In most tests, livetest will run as long as an Astakos identity manager service is accessible and kamaki is set up to authenticate a valid token on this server.
173

    
174
In specific, a setup file needs at least the following mandatory settings in the configuration file:
175

    
176
* If authentication information is used for default kamaki clients::
177

    
178
    [astakos]
179
    url=<Astakos Identity Manager URL>
180
    token=<A valid user token>
181

    
182
* else if this authentication information is only for testing add this under [livetest]::
183

    
184
    astakos_url=<Astakos Identity Manager URL>
185
    astakos_token=<A valid user token>
186

    
187
Each service tested in livetest might need some more options under the [livetest] label, as shown bellow:
188

    
189
* kamaki livetest astakos::
190

    
191
    astakos_email = <The valid email of testing user>
192
    astakos_name = <The exact "real" name of testing user>
193
    astakos_username = <The username of the testing user>
194
    astakos_uuid = <The valid unique user id of the testing user>
195

    
196
* kamaki livetest pithos::
197

    
198
    astakos_uuid = <The valid unique user id of the testing user>
199

    
200
* kamaki livetest cyclades / image::
201

    
202
    image_id = <A valid image id used for testing>
203
    image_local_path = <The local path of the testing image>
204
    image_details = <A text file containing testing image details in a python dict>
205

    
206
    - example image.details content:
207
    {
208
        u'id': u'b3e68235-3abd-4d60-adfe-1379a4f8d3fe',
209
        u'metadata': {
210
            u'values': {
211
                u'description': u'Debian 6.0.6 (Squeeze) Base System',
212
                u'gui': u'No GUI',
213
                u'kernel': u'2.6.32',
214
                u'os': u'debian',
215
                u'osfamily': u'linux',
216
                u'root_partition': u'1',
217
                u'sortorder': u'1',
218
                u'users': u'root'
219
            }
220
        },
221
        u'name': u'Debian Base',
222
        u'progress': u'100',
223
        u'status': u'ACTIVE',
224
        u'created': u'2012-11-19T14:54:57+00:00',
225
        u'updated': u'2012-11-19T15:29:51+00:00'
226
    }
227

    
228
    flavor_details = <A text file containing the testing images' flavor details in a python dict>
229

    
230
    - example flavor.details content:
231
    {
232
        u'name': u'C1R1drbd',
233
        u'ram': 1024,
234
        u'id': 1,
235
        u'SNF:disk_template': u'drbd',
236
        u'disk': 20,
237
        u'cpu': 1
238
    }
239

    
240
After setup, kamaki can run all tests::
241

    
242
    $ kamaki livetest all
243

    
244
a specific test (e.g. astakos)::
245

    
246
    $ kamaki livetest astakos
247

    
248
or a specific method from a service (e.g. astakos authenticate)::
249

    
250
    $ kamaki livetest astakos authenticate
251

    
252
The quotaholder client
253
""""""""""""""""""""""
254

    
255
A quotaholder client is introduced as an advanced feature. Quotaholder client is mostly used as a client library for accessing a synnefo quota service, but it can also be allowed as a kamaki command set, but setting the quotaholder.cli and quotaholder.url methods::
256

    
257
    [quotaholder]
258
    cli=quotaholder_cli
259
    url=<URL of quotaholder service>
260

    
261
Quotaholder is not tested in livetest
262

    
263
The unit testing system
264
"""""""""""""""""""""""
265

    
266
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 `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the `developers section <developers/extending-clients-api.html>`_.