Statistics
| Branch: | Tag: | Revision:

root / docs / setup.rst @ 76769d2f

History | View | Annotate | Download (19.6 kB)

1
Setup
2
=====
3

    
4
Kamaki is easy to install from the official repository or with the pypi mechanism.
5

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

    
9
.. warning:: Users of kamaki 0.8.X or older should consult the
10
    `migration guide <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_ first.
11

    
12
To set up Kamaki for a specific Synnefo deployment, users need an
13
**authentication URL** and a **user token**. Users should also pick an alias to
14
name the cloud configuration. This can be any single word, e.g., "default",
15
"mycloud" or whatever suits the user.
16

    
17
.. code-block:: console
18

    
19
    $ kamaki config set cloud.<cloud alias>.url <cloud-authentication-URL>
20
    $ kamaki config set cloud.<cloud alias>.token myt0k3n==
21

    
22
If only one cloud is configured, it is automatically considered the default.
23
Otherwise, a default cloud should be specified:
24

    
25
.. code-block:: console
26

    
27
    $ kamaki config set default_cloud <cloud alias>
28

    
29
The endpoints (URLs) for each service are resolved automatically from a single
30
URL. This mechanism works for Synnefo v0.14 deployments or later. The
31
authentication URL is retrieved from the Synnefo Web UI and should be set as
32
the cloud URL for kamaki. Users of Synnefo clouds >=0.14 are advised against
33
using any service-specific URLs.
34

    
35
Migrating configuration file to latest version
36
----------------------------------------------
37

    
38
Each new version of kamaki might demand some changes to the configuration file.
39
Kamaki features a mechanism of automatic migration of the configration file to
40
the latest version, which involves heuristics for guessing and translating the
41
file.
42

    
43
Quick migration
44
^^^^^^^^^^^^^^^
45

    
46
The easiest way is to backup and remove the configuration file. The default
47
configuration file location is '${HOME}/.kamakirc'.
48

    
49
To reset kamaki, a user needs the authentication URL and TOKEN:
50

    
51
.. code-block:: console
52

    
53
    $ kamaki config set cloud.default.url URL
54
    $ kamaki config set cloud.default.token TOKEN
55

    
56
After that, a new configuration file will be created. In most cases, this is
57
enough, since kamaki automatically sets the correct options for every
58
functionality.
59

    
60
Automatic migration
61
^^^^^^^^^^^^^^^^^^^
62

    
63
Another way is to let kamaki change the file automatically. Kamaki always
64
inspects the configuration file and, if understood as an older version, it
65
suggests some necessary modifications (user permission is required).
66

    
67
On example 2.1 we suggest using the `user info` command to invoke the migration
68
mechanism.
69

    
70
.. code-block:: console
71
    :emphasize-lines: 1
72

    
73
    Example 2.1: Convert config file while authenticating user "exampleuser"
74

    
75
    $ kamaki user info
76
    Config file format version >= 0.12 is required
77
    Configuration file: "/home/exampleuser/.kamakirc"
78
    but kamaki can fix this:
79
    Calculating changes while preserving information
80
    ... rescue global.token => cloud.default.token
81
    ... rescue config.cli => global.config_cli
82
    ... rescue history.file => global.history_file
83
    ... change global.network_cli value: `cyclades` => `network`
84
    ... DONE
85
    The following information will NOT be preserved:
86
        global.account =
87
        global.data_log = on
88
        user.account = exampleuser@example.com
89
        user.url = https://accounts.okeanos.grnet.gr
90
        compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1
91
        file.url = https://pithos.okeanos.grnet.gr/v1
92
        image.url = https://cyclades.okeanos.grnet.gr/plankton
93

    
94
    Kamaki is ready to convert the config file to version 0.12
95
    Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
96

    
97
At this point, we should examine the kamaki output. Most options are renamed to
98
match the latest configuration file version specifications.
99

    
100
Lets take a look at the discarded options:
101

    
102
* `global.account` and `user.account` are not used since version 0.9
103
    The same is true for the synonyms `store.account` and `pithos.account`.
104
    These options were used to explicitly set a user account or uuid to a
105
    pithos call. In the latest Synnefo version (>= 0.14), these features are
106
    meaningless and therefore omitted.
107

    
108
* `global.data_log` option has never been a valid kamaki config option.
109
    In this scenario, the user wanted to set the `log_data` option, but he or
110
    she typed `data_log` instead. To fix this, the user should manually set the
111
    correct option after the conversion is complete (Example 2.2).
112

    
113
Users should press *y* when they are ready, which will cause the default config
114
file to be modified.
115

    
116
.. code-block:: console
117
    :emphasize-lines: 1
118

    
119
    Example 2.2: Rescue misspelled log_data option
120

    
121
    $ kamaki config set log_data on
122

    
123
In order to convert more files, users may run kamaki with the -c option, which
124
runs kamaki with a different configuration file (Example 2.3) and apply the
125
steps described above.
126

    
127
.. code-block:: console
128
    :emphasize-lines: 1
129

    
130
    Example 2.3: Use kamaki to update a configuration file called ".myfilerc"
131

    
132
    $ kamaki -c .myfilerc user authenticate
133

    
134
Multiple clouds
135
---------------
136

    
137
The following refers to users of multiple Synnefo and/or Open Stack
138
deployments. In the following, a Synnefo (or Open Stack) cloud deployment will
139
be called **a cloud**.
140

    
141
Multiple clouds can be configured and manager in a single  kamaki setup, since
142
version 0.9. Each cloud corresponds to a Synnefo (or Open Stack) cloud
143
deployment, with each deployment offering a single point of authentication (an
144
**authentication URL** and **token** pair). Users can retrieve this information
145
through the cloud UI.
146

    
147
Once a user has retrieved one URL/token pair per cloud, it is time to assign a
148
name to each cloud and configure kamaki accordingly.
149

    
150
For example, let the user have access to two clouds with the following authentication information ::
151

    
152
    cloud alias: devel
153
    authentication URL: https://devel.example.com/astakos/identity/v2.0/
154
    authentication token: myd3v3170k3n==
155

    
156
    cloud alias: testing
157
    autentication URL: https://testing.example.com/astakos/identity/v2.0/
158
    authentication token: my73571ng70k3n==
159

    
160
.. note:: the cloud alias is arbitrary and decided by the user. It is just a
161
    reference label for the cloud setup in the kamaki context.
162

    
163
The user should let kamaki know about these setups:
164

    
165
.. code-block:: console
166

    
167
    $ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/
168
    $ kamaki config set cloud.devel.token myd3v3170k3n==
169
    $
170
    $ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/
171
    $ kamaki config set cloud.testing.token my73571ng70k3n==
172
    $
173

    
174
To check if all settings are loaded, a user may list all clouds, as shown
175
bellow:
176

    
177
.. code-block:: console
178

    
179
    $ kamaki config get cloud
180
     cloud.default.url = https://example.com/astakos.identity/v2.0/
181
     cloud.default.token = myd3f4u1770k3n==
182
     cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
183
     cloud.devel.token = myd3v3170k3n==
184
     cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/
185
     cloud.testing.token = my73571ng70k3n==
186
    $
187

    
188
or query kamaki for a specific cloud:
189

    
190
.. code-block:: console
191

    
192
    $ kamaki config get cloud.devel
193
     cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
194
     cloud.devel.token = myd3v3170k3n==
195
    $
196

    
197
Now kamaki can use any of these clouds, with the **- - cloud** attribute. If
198
the **- - cloud** option is omitted, kamaki will query the `default` cloud.
199

    
200
One way to test this, is the `user info` command:
201

    
202
.. code-block:: console
203

    
204
    $ kamaki --cloud=devel user info
205
     ...
206
    id         :  725d5de4-1bab-45ac-9e98-38a60a8c543c
207
    name       :  Devel User
208
    $
209
    $ kamaki --cloud=testing user info
210
     ...
211
    id         :  4ed5d527-bab1-ca54-89e9-c345c8a06a83
212
    name       :  Testing User
213
    $
214
    $ kamaki --cloud=default user info
215
     ...
216
    id         :  4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
217
    name       :  Default User
218
    $
219
    $ kamaki user info
220
     ...
221
    id         :  4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
222
    name       :  Default User
223
    $
224

    
225
In interactive cell, the cloud option should be passed when calling the shell.
226

    
227
.. code-block:: console
228

    
229
    $ kamaki-shell --cloud=devel
230
    kamaki v0.10 - Interactive Shell
231

    
232
    /exit       terminate kamaki
233
    exit or ^D  exit context
234
    ? or help   available commands
235
    ?command    help on command
236
    !<command>  execute OS shell command
237

    
238
    Session user is Devel User
239
    (uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c)
240
    [kamaki]: 
241

    
242

    
243
Optional features
244
-----------------
245

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

    
249
* ansicolors
250
    * Add colors to command line / console output
251
    * Can be switched on/off in kamaki configuration file: `colors = on/off`
252
    * Has not been tested on non unix / linux based platforms
253

    
254
* mock
255
    * For kamaki contributors only
256
    * Allow unit tests to run on kamaki.clients package
257
    * Needs mock version 1.X or better
258

    
259
Any of the above features can be installed at any time before or after kamaki
260
installation.
261

    
262
Configuration options
263
---------------------
264

    
265
There are two kinds of configuration options:
266

    
267
* kamaki-related (global)
268
    interface settings and constants of the kamaki internal mechanism, e.g.,
269
    terminal colors, maximum threads per connection, custom logging, history
270
    file path, etc.
271

    
272
* cloud-related
273
    information needed to connect and use one or more clouds. There are some
274
    mandatory options (URL, token) and some advanced / optional (e.g.,
275
    service-specific URL overrides or versions)
276

    
277
Kamaki comes with preset default values to all kamaki-related configuration
278
options. Cloud-related information is not included in presets and should be
279
provided by the user. Kamaki-related options can also be modified.
280

    
281
There are two ways of managing configuration options: edit the config file or
282
use the kamaki config command.
283

    
284
Using multiple configuration files
285
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
286

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

    
291
If a user needs to switch between different kamaki-related setups, Kamaki can
292
explicitly load configuration files with the **- - config** (or **- c**) option
293

    
294
.. code-block:: console
295

    
296
    $ kamaki --config <custom_config_file_path> [other options]
297

    
298
.. note:: For accessing multiple clouds, users do NOT need to create multiple
299
    configuration files. Instead, we suggest using a single configuration file
300
    with multiple cloud setups. More details can be found at the
301
    `multiple clouds guide <#multiple-clouds>`_.
302

    
303
Modifying options at runtime
304
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
305

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

    
308
.. code-block:: console
309

    
310
    $ kamaki file list -o global.pithos_container=anothercontainer
311

    
312
will invoke *kamaki file list* with the specified options, but the initial
313
global.pithos_container values will not be modified.
314

    
315

    
316
Editing options
317
^^^^^^^^^^^^^^^
318

    
319
Kamaki config command allows users to see and manage all configuration options.
320

    
321
* kamaki config list
322
    lists all configuration options
323

    
324
* kamaki config get <group>[.option] | <option>
325
    show the value of a configuration option.A single *option* is equivalent to
326
    *global.option*, except if this group exist (*global*, *cloud*)
327

    
328
* kamaki config set <group.option> <value>
329
    set the group.option to value. If no group is given, it defaults to
330
    *global*.
331

    
332
* kamaki config delete <group>[.option] | <option>
333
    delete a configuration option, group, or global option.
334

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

    
337
The commands above can also be used for **clouds** handling, using the `cloud.`
338
prefix. The cloud handling cases are similar but with slightly different
339
semantics:
340

    
341
* kamaki config get cloud[.<cloud alias>[.option]]
342
    * cloud
343
        list all clouds and their settings
344
    * cloud.<cloud alias>
345
        list settings of the cloud aliased as <cloud alias>. If no
346
        special is configured, use the term `cloud.default`
347
    * cloud.<cloud alias>.<option>
348
        show the value of the specified option. If no special alias is
349
        configured, use `cloud.default.<option>`
350

    
351
* kamaki config set cloud.<cloud alias>.<option> <value>
352
    If the cloud alias <cloud alias> does not exist, create it. Then, create
353
    (or update) the option <option> of this cloud, by setting its value
354
    to <value>.
355

    
356
* kamaki config delete cloud.<cloud alias>[.<option>]
357
    * cloud.<cloud alias>
358
        delete the cloud alias <cloud alias> and all its options
359
    * cloud.<cloud alias>.<option>
360
        delete the <option> and its value from the cloud cloud aliased as
361
        <cloud alias>
362

    
363
To see if a default cloud is configured, get the default_cloud value
364

    
365
    .. code-block:: console
366

    
367
        $ kamaki config get default_cloud
368

    
369
If no default_cloud value is set, the first cloud alias is picked as default.
370
To pick a cloud alias as default:
371

    
372
    .. code-block:: console
373

    
374
        $ kamaki config set default_cloud <cloud alias>
375

    
376

    
377
Editing the configuration file
378
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
379

    
380
The configuration file is a simple text file that can be created by the user.
381

    
382
.. note:: users of kamaki < 0.9 can use the latest versions to automatically
383
    convert their old configuration files to the new configuration file(s). See
384
    `these instructions <#mMigrating-configuration-file-to-latest-version>`_
385
    for more.
386

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

    
390
.. code-block:: console
391

    
392
    $ kamaki config set log_file /home/exampleuser/logs/kamaki.log
393

    
394
In the above example, if the kamaki configuration file does not exist, it will
395
be created with all the default values plus the *global.log_file* option set to
396
`/home/exampleuser/logs/kamaki.log`
397

    
398
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::
399

    
400
    [global]
401
    log_file = /home/exampleuser/logs/kamaki.log
402
    max_threads = 7
403
    colors = off
404

    
405
    [cloud "default"]
406
    url =
407
    token =
408

    
409
In this scenario, a bunch of configuration options are created and set to their
410
default options, except the log_file option which is set to whatever the
411
specified value.
412

    
413
The *[cloud "default"]* section is special and is used to configure the default
414
cloud. Kamaki will not be able to do anything useful without proper url and
415
token values set in the cloud section.
416

    
417
Available options
418
^^^^^^^^^^^^^^^^^
419

    
420
The [*global*] group is treated by kamaki as a generic group for kamaki
421
settings, namely command cli specifications, the thread limit, console colors,
422
history and log files, log detail options and pithos-specific options.
423

    
424
* global.default_cloud <cloud name>
425
    pick a cloud configuration as default. It must refer to an existing cloud.
426

    
427
* global.colors <on|off>
428
    enable / disable colors in command line based uis. Requires ansicolors,
429
    otherwise it is ignored
430

    
431
* global.log_file <logfile full path>
432
    set a custom location for kamaki logging. Default value is ~/.kamaki.log
433

    
434
* global.log_token <on|off>
435
    allow kamaki to log user tokens
436

    
437
* global.log_data <on|off>
438
    allow kamaki to log http data (by default, it logs only method, URL and
439
    headers)
440

    
441
* global.log_pid <on|off>
442
    attach the process name and id that produces each log line. Useful for
443
    resolving race condition problems.
444

    
445
* global.file_cli <UI command specifications for file>
446
    a special package that is used to load storage commands to kamaki UIs.
447
    Don't touch this unless if you know what you are doing.
448

    
449
* global.cyclades_cli <UI command specifications for cyclades>
450
    a special package that is used to load cyclades commands to kamaki UIs.
451
    Don't touch this unless you know what you are doing.
452

    
453
* global.flavor_cli <UI command specifications for VM flavors>
454
    a special package that is used to load cyclades VM flavor commands to
455
    kamaki UIs. Don't touch this unless you know what you are doing.
456

    
457
* global.network_cli <UI command specifications for virtual networks>
458
    a special package that is used to load cyclades virtual network commands.
459
    Don't touch this unless you know what you are doing.
460

    
461
* global.ip_cli <UI command specifications for floating IPs>
462
    a special package that is used to load cyclades floating IP commands. Don't
463
    touch this unless you know what you are doing.
464

    
465
* global.image_cli <UI command specs for Plankton or Compute image service>
466
    a special package that is used to load image-related commands to kamaki UIs.
467
    Don't touch this unless you know what you are doing.
468

    
469
* global.user_cli <UI command specs for Astakos authentication service>
470
    a special package that is used to load astakos-related commands to kamaki
471
    UIs. Don't touch this unless you know what you are doing.
472

    
473
* global.history_file <history file path>
474
    the path of a simple file for inter-session kamaki history. Make sure
475
    kamaki is executed in a context where this file is accessible for reading
476
    and writing. Kamaki automatically creates the file if it doesn't exist
477

    
478
Additional features
479
^^^^^^^^^^^^^^^^^^^
480

    
481
Functional tests
482
""""""""""""""""
483

    
484
Kamaki contains a set of functional tests for *kamaki.clients*, called
485
"livetest". The term "live" means that the tests are performed against an
486
on-line functional cloud deployment. The package is accessible as
487
*kamaki.clients.livetest* .
488

    
489
The livetest commands can be activated by setting the following option in the
490
configuration file::
491

    
492
    [global]
493
    livetest_cli=livetest
494

    
495
or with this kamaki command::
496

    
497
    $ kamaki config set livetest_cli livetest
498

    
499
In most cases, it is enough to have the default cloud configured correctly.
500
Some commands, though, require some extra settings specific to actual contents
501
of the cloud or the example files used in kamaki.
502

    
503
Here is a list of settings needed:
504

    
505
* for all tests::
506
    * livetest.testcloud = <the cloud alias this test will run against>
507

    
508
* for astakos client::
509
    * livetest.astakos_details = <A file with an authentication output>
510
        To create this file, pipeline the output of an authentication command
511
        with the -j option for raw json output
512

    
513
        .. code-block:: console
514

    
515
            $ kamaki user authenticate -j > astakos.details
516

    
517
    * livetest.astakos_name = <The exact "real" name of the testing user>
518
    * livetest.astakos_id = <The valid unique user id of the testing user>
519

    
520
* for image client:
521
    * livetest.image_details = <A file with the image metadata>
522
        To create this file, pipeline the output of an image metadata command
523
        with the -j option for raw json output
524

    
525
        .. code-block:: console
526

    
527
            $ kamaki image info <img id> -j > img.details
528

    
529
    * livetest.image_id = <A valid image id used for testing>
530
    * livetest.image_local_path = <The local path of the testing image>
531

    
532
* for flavors (part of the compute client):
533
    * livetest.flavor_details = <A file with the flavor details>
534
        To create this file, pipeline the output of a flavor info command
535
        with the -j option for raw json output
536

    
537
        .. code-block:: console
538

    
539
            $ kamaki flavor info <flavor id> -j > flavor.details
540

    
541

    
542
After setup, kamaki can run all tests::
543

    
544
    $ kamaki livetest all
545

    
546
a specific test (e.g., pithos scenario)::
547

    
548
    $ kamaki livetest pithos
549

    
550
or a specific method from a service (e.g., create_server @ cyclades)::
551

    
552
    $ kamaki livetest cyclades create_server
553

    
554

    
555
Unit tests
556
""""""""""
557

    
558
Kamaki features a set of unit tests for the kamaki.clients package. This set is
559
not used when kamaki is running. Instead, it is aimed to developers who debug
560
or extent kamaki. For more information, check the
561
`Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the
562
`developers section <developers/extending-clients-api.html>`_.