Revision 2bd23362 docs/setup.rst

b/docs/setup.rst
8 8
Quick Setup
9 9
-----------
10 10

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

  
14 14
Kamaki has to be configured for a specific Synnefo deployment, with an
15 15
authentication url and user token pair. Users should also pick an alias to name
16
the cloud configuration. This can be any single word, e.g., "default", "mycloud"
17
or whatever suits kamaki users.
16
the cloud configuration. This can be any single word, e.g., "default",
17
"mycloud"or whatever suits the user.
18 18

  
19 19
.. code-block:: console
20 20

  
......
31 31
Since version 0.14, Synnefo supports a single authentication URL for retrieving
32 32
all API endpoints. This URL is retrieved from the Synnefo Web UI and should be
33 33
set as the cloud URL for kamaki. All service-specific URLs are retrieved and
34
handled automatically by kamaki, through this URL. Users of Synnefo clouds
35
>=0.14 are advised against using any service-specific URLs.
34
handled automatically. Users of Synnefo clouds >=0.14 are advised against using
35
any service-specific URLs.
36 36

  
37
Migrating from kamaki 0.8.X to 0.9
38
----------------------------------
37
Migrating from kamaki 0.8.X to 0.9 or better
38
--------------------------------------------
39 39

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

  
47 47
Existing kamaki users should convert their configuration files to v9. To do
48 48
that, kamaki 0.9 can inspect the configuration file and suggests a list of
49
config file transformations, which are performed automatically (after users'
50
permission). This mechanism is invoked when an API-related kamaki command is
51
fired. On example 2.1 we suggest using the `user authenticate` command to fire
52
the kamaki config file conversion mechanism.
49
config file transformations, which are performed automatically after users'
50
permission. This mechanism is invoked when an API-related kamaki command is
51
fired. On example 2.1 we suggest using the `user authenticate` command to start
52
the conversion mechanism for the configuration file.
53 53

  
54 54
.. code-block:: console
55 55
    :emphasize-lines: 1
......
78 78
    Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
79 79

  
80 80
At this point, we should examine the kamaki output. Most options are renamed to
81
be understood by the new kamaki.
81
match the latest configuration file version specifications.
82 82

  
83 83
Let's take a look at the discarded options:
84 84

  
......
89 89
    meaningless and therefore omitted.
90 90

  
91 91
* `global.data_log` option has never been a valid kamaki config option.
92
    In this example, the user accidentally misspelled the term `log_data`
93
    (which is a valid kamaki config option) as `data_log`. To fix this, the
94
    user should set the correct option after the conversion is complete
95
    (Example 2.2).
92
    In this scenario, the user wanted to set the `log_data` option, but he or
93
    she typed `data_log` instead. To fix this, the user should manually set the
94
    correct option after the conversion is complete (Example 2.2).
96 95

  
97
Users should press *y* when they are ready. Kamaki has now modified the default
98
config file to conform with kamaki config file v3. Now users should rescue
99
unrescued information (if any).
96
Users should press *y* when they are ready, which will cause the default config
97
file to be modified so that it conforms with the latest version.
100 98

  
101 99
.. code-block:: console
102 100
    :emphasize-lines: 1
......
121 119

  
122 120
The following refers to users of multiple Synnefo and/or Open Stack
123 121
deployments. In the following, a Synnefo or Open Stack cloud deployment will
124
frequently be called as a **cloud**.
122
be called **a cloud**.
125 123

  
126
Kamaki supports accessing multiple clouds from the same kamaki setup. Before
127
kamaki 0.9, this was possible only by using multiple config files. Since 0.9,
128
kamaki supports multiple clouds in the same configuration.
129

  
130
Each cloud corresponds to a Synnefo (or Open Stack) cloud deployment.
131
Since Synnefo version 0.14, each deployment offers a single point of
132
authentication, as an **authentication URL** and **token** pair. Users can
133
retrieve this information through the cloud UI.
124
Multiple clouds can be configured and manager in a single  kamaki setup, since
125
version 0.9. Each cloud corresponds to a Synnefo (or Open Stack) cloud
126
deployment, with each deployment offering a single point of authentication (an
127
**authentication URL** and **token** pair). Users can retrieve this information
128
through the cloud UI.
134 129

  
135 130
Once a user has retrieved one URL/token pair per cloud, it is time to assign a
136
name to each cloud and let kamaki know about them.
131
name to each cloud and configure kamaki accordingly.
137 132

  
138 133
For example, let the user have access to two clouds with the following authentication information ::
139 134

  
......
146 141
    authentication token: my73571ng70k3n==
147 142

  
148 143
.. note:: the cloud alias is arbitrary and decided by the user. It is just a
149
    name to call a cloud setup in the kamaki context.
144
    reference label for the cloud setup in the kamaki context.
150 145

  
151 146
The user should let kamaki know about these setups:
152 147

  
......
164 159

  
165 160
.. code-block:: console
166 161

  
167
    $ kamaki config getcloud
162
    $ kamaki config get cloud
168 163
     cloud.default.url = https://example.com/astakos.identity/v2.0/
169
     cloud.default.url = myd3f4u1770k3n==
164
     cloud.default.token = myd3f4u1770k3n==
170 165
     cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
171 166
     cloud.devel.token = myd3v3170k3n==
172 167
     cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/
......
214 209
        name       :  Default User
215 210
    $
216 211

  
217
In interactive cell, the cloud is picked when invoking the shell, with
212
In interactive cell, the cloud can be picked when invoking the shell, with
218 213
the **- - cloud** option.
219 214

  
215
.. code-block:: console
216

  
217
    $ kamaki --cloud=devel
218
    kamaki v0.10 - Interactive Shell
219

  
220
    /exit       terminate kamaki
221
    exit or ^D  exit context
222
    ? or help   available commands
223
    ?command    help on command
224
    !<command>  execute OS shell command
225

  
226
    Session user is Devel User
227
    (uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c)
228
    [kamaki]: 
229

  
230

  
220 231
Optional features
221 232
-----------------
222 233

  
......
233 244
    * Allow unit tests to run on kamaki.clients package
234 245
    * Needs mock version 1.X or better
235 246

  
236
* astakosclient
237
    * For advanced users mostly
238
    * Allows the use of a full astakos command line client
239

  
240 247
Any of the above features can be installed at any time before or after kamaki
241 248
installation.
242 249

  
......
247 254

  
248 255
* kamaki-related (global)
249 256
    interface settings and constants of the kamaki internal mechanism, e.g.,
250
    colors in the output, maximum threads per connection, custom logging or
251
    history files, etc.
257
    terminal colors, maximum threads per connection, custom logging, history
258
    file path, etc.
252 259

  
253 260
* cloud-related
254 261
    information needed to connect and use one or more clouds. There are some
......
284 291
Modifying options at runtime
285 292
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
286 293

  
287
All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
294
All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example:
288 295

  
289 296
.. code-block:: console
290 297

  
......
293 300
will invoke *kamaki file list* with the specified options, but the initial
294 301
global.pithos_container values will not be modified.
295 302

  
303

  
296 304
Editing options
297 305
^^^^^^^^^^^^^^^
298 306

  
299 307
Kamaki config command allows users to see and manage all configuration options.
300 308

  
301 309
* kamaki config list
302
    lists all configuration options currently used by a Kamaki installation
310
    lists all configuration options of a kamaki setup
303 311

  
304 312
* kamaki config get <group.option>
305 313
    show the value of a specific configuration option. Options must be of the
306
    form *group.option*. The term *option* is equivalent to *global.option*
314
    form *group.option*. A single *option* is equivalent to *global.option*,
315
    with the exception of the term *cloud* (see bellow)
307 316

  
308 317
* kamaki config set <group.option> <value>
309
    set the group.option to value. If no group is given, the defaults to
318
    set the group.option to value. If no group is given, it defaults to
310 319
    *global*.
311 320

  
312 321
* kamaki config delete <group.option>
313
    delete a configuration option. If no group is given, the defaults to
322
    delete a configuration option. If no group is given, it defaults to
314 323
    *global*
315 324

  
316 325
The above commands cause option values to be permanently stored in the Kamaki configuration file.
......
341 350
        delete the <option> and its value from the cloud cloud aliased as
342 351
        <cloud alias>
343 352

  
344
.. note:: To see if a default cloud is configured, get the default_cloud value
353
To see if a default cloud is configured, get the default_cloud value
345 354

  
346 355
    .. code-block:: console
347 356

  
348 357
        $ kamaki config get default_cloud
349 358

  
359
If no default_cloud value is set, the first cloud alias is picked as default.
360
To pick a cloud alias as default:
361

  
362
    .. code-block:: console
363

  
364
        $ kamaki config set default_cloud <cloud alias>
365

  
366

  
350 367
Editing the configuration file
351 368
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
352 369

  
353 370
The configuration file is a simple text file that can be created by the user.
354 371

  
355
.. note:: users of kamaki < 0.9 can use kamaki 0.9.X to automatically convert
356
    their old configuration files to the new config file version (>= 3.0). To
357
    do this, follow `these instructions <#migrating-from-kamaki-0-8-x-to-0-9>`_
372
.. note:: users of kamaki < 0.9 can use the latest versions to automatically
373
    convert their old configuration files to the new configuration file(s).
374
    See `these instructions <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_
375
    for more.
358 376

  
359 377
A simple way to create the configuration file is to set a configuration option
360 378
using the kamaki config command. For example:
......
378 396
    url =
379 397
    token =
380 398

  
381
A bunch of configuration options are created and set to their default options,
382
except the log_file option which is set to whatever the specified value.
383

  
384
The [cloud "default"] section is special and is used to configure the default
385
cloud cloud. Kamaki will not be able to run without setting the url and token
386
values to that section.
399
In this scenario, a bunch of configuration options are created and set to their
400
default options, except the log_file option which is set to whatever the
401
specified value.
387 402

  
388
More clouds can be created  on the side of the default cloud, e.g., using the
389
examples at the `multiple clouds guide <#multiple-clouds>`_ ::
390

  
391
    [cloud "devel"]
392
    url = https://devel.example.com/astakos/identity/v2.0/
393
    token = myd3v3170k3n==
394

  
395
    [cloud "testing"]
396
    url = https://testing.example.com/astakos/identity/v2.0/
397
    token = my73571ng70k3n==
403
The *[cloud "default"]* section is special and is used to configure the default
404
cloud. Kamaki will not be able to do anything useful without proper url and
405
token values set in the cloud section.
398 406

  
399 407
Available options
400 408
^^^^^^^^^^^^^^^^^
401 409

  
402
The [global] group is treated by kamaki as a generic group for kamaki-related
410
The [*global*] group is treated by kamaki as a generic group for kamaki
403 411
settings, namely command cli specifications, the thread limit, console colors,
404 412
history and log files, log detail options and pithos-specific options.
405 413

  
......
416 424
    allow kamaki to log http data (by default, it logs only method, URL and
417 425
    headers)
418 426

  
427
* global.log_pid <on|off>
428
    attach the process name and id that produces each log line. Useful for
429
    resolving race condition problems.
430

  
419 431
* global.file_cli <UI command specifications for file>
420 432
    a special package that is used to load storage commands to kamaki UIs.
421 433
    Don't touch this unless if you know what you are doing.
......
447 459
Additional features
448 460
^^^^^^^^^^^^^^^^^^^
449 461

  
450
The livetest suite
451
""""""""""""""""""
462
Functional tests
463
""""""""""""""""
452 464

  
453
Kamaki contains a live test suite for the kamaki.clients API, where "live"
454
means that the tests are performed against active services that up and running.
455
The live test package is named "livetest", it is accessible as kamaki.clients.
456
livetest and it is designed to check the actual relation between kamaki and
457
synnefo services.
465
Kamaki contains a set of functional tests for *kamaki.clients*, called
466
"livetest". The term "live" means that the tests are performed against an
467
on-line functional cloud deployment. The package is accessible as
468
*kamaki.clients.livetest* .
458 469

  
459
The livetest suite can be activated with the following option on the configuration file::
470
The livetest commands can be activated by setting the following option in the
471
configuration file::
460 472

  
461 473
    [global]
462 474
    livetest_cli=livetest
463 475

  
464 476
or with this kamaki command::
465 477

  
466
    kamaki config set livetest_cli livetest
478
    $ kamaki config set livetest_cli livetest
467 479

  
468
In most tests, livetest will run as long as the default cloud is configured
469
correctly. Some commands, though, need some extra settings related to the cloud
470
the test is performed against, or the example files used in kamaki.
480
In most cases, it is enough to have the default cloud configured correctly.
481
Some commands, though, require some extra settings specific to actual contents
482
of the cloud or the example files used in kamaki.
471 483

  
472 484
Here is a list of settings needed:
473 485

  
......
477 489
* for astakos client::
478 490
    * livetest.astakos_details = <A file with an authentication output>
479 491
        To create this file, pipeline the output of an authentication command
480
        with the -j option for raw jason output
492
        with the -j option for raw json output
481 493

  
482 494
        .. code-block:: console
483 495

  
484 496
            $ kamaki user authenticate -j > astakos.details
485 497

  
486
    * livetest.astakos_name = <The exact "real" name of testing user>
498
    * livetest.astakos_name = <The exact "real" name of the testing user>
487 499
    * livetest.astakos_id = <The valid unique user id of the testing user>
488 500

  
489 501
* for image client:
490
    * livetest.image_details = <A file with the image's metadata>
502
    * livetest.image_details = <A file with the image metadata>
491 503
        To create this file, pipeline the output of an image metadata command
492
        with the -j option for raw jason output
504
        with the -j option for raw json output
493 505

  
494 506
        .. code-block:: console
495 507

  
......
501 513
* for flavors (part of the compute client):
502 514
    * livetest.flavor_details = <A file with the flavor details>
503 515
        To create this file, pipeline the output of a flavor info command
504
        with the -j option for raw jason output
516
        with the -j option for raw json output
505 517

  
506 518
        .. code-block:: console
507 519

  
......
512 524

  
513 525
    $ kamaki livetest all
514 526

  
515
a specific test (e.g., astakos)::
527
a specific test (e.g., pithos scenario)::
528

  
529
    $ kamaki livetest pithos
516 530

  
517
    $ kamaki livetest astakos
531
or a specific method from a service (e.g., create_server @ cyclades)::
518 532

  
519
or a specific method from a service (e.g., astakos authenticate)::
533
    $ kamaki livetest cyclades create_server
520 534

  
521
    $ kamaki livetest astakos authenticate
522 535

  
523 536
The unit testing system
524 537
"""""""""""""""""""""""
525 538

  
526 539
Kamaki container a set of finegrained unit tests for the kamaki.clients
527 540
package. This set is not used when kamaki is running. Instead, it is aimed to
528
developers who debug or extent the kamaki clients library. For more
529
information, check the
541
developers who debug or extent kamaki. For more information, check the
530 542
`Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the
531 543
`developers section <developers/extending-clients-api.html>`_.

Also available in: Unified diff