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.
11 Existing kamaki users should consult the
12 `migration guide <#migrating-from-kamaki-0-8-x-to-0-9>`_ first.
14 Kamaki has to be configured for a specific Synnefo deployment, with an
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.
19 .. code-block:: console
21 $ kamaki config set cloud.<cloud alias>.url <cloud-authentication-URL>
22 $ kamaki config set cloud.<cloud alias>.token myt0k3n==
24 If only one cloud is configured, kamaki automatically picks it as the default.
25 Otherwise, a default cloud should be specified:
27 .. code-block:: console
29 $ kamaki config set default_cloud <cloud alias>
31 Since Synnefo version 0.14, a synnefo cloud UI offers a single authentication
32 URL, which should be set as the cloud URL for kamaki. All service-specific URLs
33 are retrieved and handled automatically by kamaki, through this URL. Users of
34 synnefo clouds >=0.14 are advised against using any service-specific URLs.
36 Migrating from kamaki 0.8.X to 0.9
37 ----------------------------------
39 This section refers to running installations of kamaki version <= 0.8.X To
40 check the current kamaki version:
42 .. code-block:: console
46 Existing kamaki users should convert their configuration files to v9. To do
47 that, kamaki 0.9 can inspect the configuration file and suggests a list of
48 config file transformations, which are performed automatically (after users'
49 permission). This mechanism is invoked when an API-related kamaki command is
50 fired. On example 2.1 we suggest using the `user authenticate` command to fire
51 the kamaki config file conversion mechanism.
53 .. code-block:: console
56 Example 2.1: Convert config file while authenticating user "exampleuser"
58 $ kamaki user authenticate
59 Config file format version >= 9.0 is required
60 Configuration file: "/home/exampleuser/.kamakirc"
61 but kamaki can fix this:
62 Calculating changes while preserving information
63 ... rescue global.token => cloud.default.token
64 ... rescue config.cli => global.config_cli
65 ... rescue history.file => global.history_file
67 The following information will NOT be preserved:
70 user.account = exampleuser@example.com
71 user.url = https://accounts.okeanos.grnet.gr
72 compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1
73 file.url = https://pithos.okeanos.grnet.gr/v1
74 image.url = https://cyclades.okeanos.grnet.gr/plankton
76 Kamaki is ready to convert the config file to version 9.0
77 Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
79 At this point, we should examine the kamaki output. Most options are renamed to
80 be understood by the new kamaki.
82 Let's take a look at the discarded options:
84 * `global.account` and `user.account` are not used anymore.
85 The same is true for the synonyms `store.account` and `pithos.account`.
86 These options were used to explicitly set a user account or uuid to a
87 pithos call. In the latest Synnefo version (>= 0.14), these features are
88 meaningless and therefore omitted.
90 * `global.data_log` option has never been a valid kamaki config option.
91 In this example, the user accidentally misspelled the term `log_data`
92 (which is a valid kamaki config option) as `data_log`. To fix this, the
93 user should set the correct option after the conversion is complete
96 Users should press *y* when they are ready. Kamaki has now modified the default
97 config file to conform with kamaki config file v3. Now users should rescue
98 unrescued information (if any).
100 .. code-block:: console
103 Example 2.2: Rescue misspelled log_data option
105 $ kamaki config set log_data on
107 In order to convert more files, users may run kamaki with the -c option, which
108 runs kamaki with a different configuration file (Example 2.3) and apply the
109 steps described above.
111 .. code-block:: console
114 Example 2.3: Use kamaki to update a configuration file called ".myfilerc"
116 $ kamaki -c .myfilerc user authenticate
121 The following refers to users of multiple Synnefo and/or Open Stack
122 deployments. In the following, a Synnefo or Open Stack cloud deployment will
123 frequently be called as a **cloud**.
125 Kamaki supports accessing multiple clouds from the same kamaki setup. Before
126 kamaki 0.9, this was possible only by using multiple config files. Since 0.9,
127 kamaki supports multiple clouds in the same configuration.
129 Each cloud corresponds to a Synnefo (or Open Stack) cloud deployment.
130 Since Synnefo version 0.14, each deployment offers a single point of
131 authentication, as an **authentication URL** and **token** pair. Users can
132 retrieve this information through the cloud UI.
134 Once a user has retrieved one URL/token pair per cloud, it is time to assign a
135 name to each cloud and let kamaki know about them.
137 For example, let the user have access to two clouds with the following authentication information ::
140 authentication URL: https://devel.example.com/astakos/identity/v2.0/
141 authentication token: myd3v3170k3n==
144 autentication URL: https://testing.example.com/astakos/identity/v2.0/
145 authentication token: my73571ng70k3n==
147 .. note:: the cloud alias is arbitrary and decided by the user. It is just a
148 name to call a cloud setup in the kamaki context.
150 The user should let kamaki know about these setups:
152 .. code-block:: console
154 $ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/
155 $ kamaki config set cloud.devel.token myd3v3170k3n==
157 $ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/
158 $ kamaki config set cloud.testing.token my73571ng70k3n==
161 To check if all settings are loaded, a user may list all clouds, as shown
164 .. code-block:: console
166 $ kamaki config getcloud
167 cloud.default.url = https://example.com/astakos.identity/v2.0/
168 cloud.default.url = myd3f4u1770k3n==
169 cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
170 cloud.devel.token = myd3v3170k3n==
171 cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/
172 cloud.testing.token = my73571ng70k3n==
175 or query kamaki for a specific cloud:
177 .. code-block:: console
179 $ kamaki config get cloud.devel
180 cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
181 cloud.devel.token = myd3v3170k3n==
184 Now kamaki can use any of these clouds, with the **- - cloud** attribute. If
185 the **- - cloud** option is ommited, kamaki will query the `default` cloud.
187 One way to test this, is the `user athenticate` command:
189 .. code-block:: console
191 $ kamaki --cloud=devel user authenticate
194 id : 725d5de4-1bab-45ac-9e98-38a60a8c543c
197 $ kamaki --cloud=testing user authenticate
200 id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83
203 $ kamaki --cloud=default user authenticate
206 id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
209 $ kamaki user authenticate
212 id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
216 In interactive cell, the cloud is picked when invoking the shell, with
217 the **- - cloud** option.
222 For installing any or all of the following, consult the
223 `kamaki installation guide <installation.html#install-ansicolors>`_
226 * Add colors to command line / console output
227 * Can be switched on/off in kamaki configuration file: `colors = on/off`
228 * Has not been tested on non unix / linux based platforms
231 * For kamaki contributors only
232 * Allow unit tests to run on kamaki.clients package
233 * Needs mock version 1.X or better
236 * For advanced users mostly
237 * Allows the use of a full astakos command line client
239 Any of the above features can be installed at any time before or after kamaki
242 Configuration options
243 ---------------------
245 There are two kinds of configuration options:
247 * kamaki-related (global)
248 interface settings and constants of the kamaki internal mechanism, e.g.
249 colors in the output, maximum threads per connection, custom logging or
253 information needed to connect and use one or more clouds. There are some
254 mandatory options (URL, token) and some advanced / optional (e.g.
255 service-specific URL overrides or versions)
257 Kamaki comes with preset default values to all kamaki-releated configuration
258 options. Cloud-related information is not included in presets and should be
259 provided by the user. Kamaki-related options can also be modified.
261 There are two ways of managing configuration options: edit the config file or
262 use the kamaki config command.
264 Using multiple configuration files
265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
267 Kamaki setups are stored in configuration files. By default, a Kamaki
268 installation stores options in *.kamakirc* file located at the user home
271 If a user needs to switch between different kamaki-related setups, Kamaki can
272 explicitly load configuration files with the **- - config** (or **- c**) option
274 .. code-block:: console
276 $ kamaki --config <custom_config_file_path> [other options]
278 .. note:: For accessing multiple clouds, users do NOT need to create multiple
279 configuration files. Instead, we suggest using a single configuration file
280 with multiple cloud setups. More details can be found at the
281 `multiple clouds guide <#multiple-clouds>`_.
283 Modifying options at runtime
284 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
286 All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
288 .. code-block:: console
290 $ kamaki file list -o global.pithos_container=anothercontainer
292 will invoke *kamaki file list* with the specified options, but the initial
293 global.pithos_container values will not be modified.
298 Kamaki config command allows users to see and manage all configuration options.
301 lists all configuration options currently used by a Kamaki installation
303 * kamaki config get <group.option>
304 show the value of a specific configuration option. Options must be of the
305 form *group.option*. The term *option* is equivalent to *global.option*
307 * kamaki config set <group.option> <value>
308 set the group.option to value. If no group is given, the defaults to
311 * kamaki config delete <group.option>
312 delete a configuration option. If no group is given, the defaults to
315 The above commands cause option values to be permanently stored in the Kamaki configuration file.
317 The commands above can also be used for **clouds** handling, using the `cloud.`
318 prefix. The cloud handling cases are similar but with slightly different
321 * kamaki config get cloud[.<cloud alias>[.option]]
323 list all clouds and their settings
324 * cloud.<cloud alias>
325 list settings of the cloud aliased as <cloud alias>. If no
326 special is configured, use the term `cloud.default`
327 * cloud.<cloud alias>.<option>
328 show the value of the specified option. If no special alias is
329 configured, use `cloud.default.<option>`
331 * kamaki config set cloud.<cloud alias>.<option> <value>
332 If the cloud alias <cloud alias> does not exist, create it. Then, create
333 (or update) the option <option> of this cloud, by setting its value
336 * kamaki config delete cloud.<cloud alias>[.<option>]
337 * cloud.<cloud alias>
338 delete the cloud alias <cloud alias> and all its options
339 * cloud.<cloud alias>.<option>
340 delete the <option> and its value from the cloud cloud aliased as
343 .. note:: To see if a default cloud is configured, get the default_cloud value
345 .. code-block:: console
347 $ kamaki config get default_cloud
349 Editing the configuration file
350 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
352 The configuration file is a simple text file that can be created by the user.
354 .. note:: users of kamaki < 0.9 can use kamaki 0.9.X to automatically convert
355 their old configuration files to the new config file version (>= 3.0). To
356 do this, follow `these instructions <#migrating-from-kamaki-0-8-x-to-0-9>`_
358 A simple way to create the configuration file is to set a configuration option
359 using the kamaki config command. For example:
361 .. code-block:: console
363 $ kamaki config set global.log_file /home/exampleuser/logs/kamaki.log
365 In the above example, if the kamaki configuration file does not exist, it will
366 be created with all the default values plus the *global.log_file* option set to
367 `/home/exampleuser/logs/kamaki.log`
369 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::
372 log_file = /home/exampleuser/logs/kamaki.log
380 A bunch of configuration options are created and set to their default options,
381 except the log_file option which is set to whatever the specified value.
383 The [cloud "default"] section is special and is used to configure the default
384 cloud cloud. Kamaki will not be able to run without setting the url and token
385 values to that section.
387 More clouds can be created on the side of the default cloud, e.g using the
388 examples at the `multiple clouds guide <#multiple-clouds>`_ ::
391 url = https://devel.example.com/astakos/identity/v2.0/
392 token = myd3v3170k3n==
395 url = https://testing.example.com/astakos/identity/v2.0/
396 token = my73571ng70k3n==
401 The [global] group is treated by kamaki as a generic group for kamaki-related
402 settings, namely command cli specifications, the thread limit, console colors,
403 history and log files, log detail options and pithos-specific options.
405 * global.colors <on|off>
406 enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored
408 * global.log_file <logfile full path>
409 set a custom location for kamaki logging. Default value is ~/.kamaki.log
411 * global.log_token <on|off>
412 allow kamaki to log user tokens
414 * global.log_data <on|off>
415 allow kamaki to log http data (by default, it logs only method, URL and
418 * global.file_cli <UI command specifications for file>
419 a special package that is used to load storage commands to kamaki UIs.
420 Don't touch this unless if you know what you are doing.
422 * global.cyclades_cli <UI command specifications for cyclades>
423 a special package that is used to load cyclades commands to kamaki UIs.
424 Don't touch this unless you know what you are doing.
426 * global.flavor_cli <UI command specifications for VM flavors>
427 a special package that is used to load cyclades VM flavor commands to
428 kamaki UIs. Don't touch this unless you know what you are doing.
430 * global.network_cli <UI command specifications for virtual networks>
431 a special package that is used to load cyclades virtual network commands to
432 kamaki UIs. Don't touch this unless you know what you are doing.
434 * global.image_cli <UI command specs for Plankton or Compute image service>
435 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.
437 * global.user_cli <UI command specs for Astakos authentication service>
438 a special package that is used to load astakos-related commands to kamaki
439 UIs. Don't touch this unless you know what you are doing.
441 * global.history_file <history file path>
442 the path of a simple file for inter-session kamaki history. Make sure
443 kamaki is executed in a context where this file is accessible for reading
444 and writing. Kamaki automatically creates the file if it doesn't exist
452 Kamaki contains a live test suite for the kamaki.clients API, where "live"
453 means that the tests are performed against active services that up and running.
454 The live test package is named "livetest", it is accessible as kamaki.clients.
455 livetest and it is designed to check the actual relation between kamaki and
458 The livetest suite can be activated with the following option on the configuration file::
461 livetest_cli=livetest
463 or with this kamaki command::
465 kamaki config set livetest_cli livetest
467 In most tests, livetest will run as long as the default cloud is configured
468 correctly. Some commands, though, need some extra settings related to the cloud
469 the test is performed against, or the example files used in kamaki.
471 Here is a list of settings needed:
474 * livetest.testcloud = <the cloud alias this test will run against>
476 * for astakos client::
477 * livetest.astakos_details = <A file with an authentication output>
478 To create this file, pipeline the output of an authentication command
479 with the -j option for raw jason output
481 .. code-block:: console
483 $ kamaki user authenticate -j > astakos.details
485 * livetest.astakos_name = <The exact "real" name of testing user>
486 * livetest.astakos_id = <The valid unique user id of the testing user>
489 * livetest.image_details = <A file with the image's metadata>
490 To create this file, pipeline the output of an image metadata command
491 with the -j option for raw jason output
493 .. code-block:: console
495 $ kamaki image meta <img id> -j > img.details
497 * livetest.image_id = <A valid image id used for testing>
498 * livetest.image_local_path = <The local path of the testing image>
500 * for flavors (part of the compute client):
501 * livetest.flavor_details = <A file with the flavor details>
502 To create this file, pipeline the output of a flavor info command
503 with the -j option for raw jason output
505 .. code-block:: console
507 $ kamaki flavor info <flavor id> -j > flavor.details
510 After setup, kamaki can run all tests::
512 $ kamaki livetest all
514 a specific test (e.g. astakos)::
516 $ kamaki livetest astakos
518 or a specific method from a service (e.g. astakos authenticate)::
520 $ kamaki livetest astakos authenticate
522 The unit testing system
523 """""""""""""""""""""""
525 Kamaki container a set of finegrained unit tests for the kamaki.clients
526 package. This set is not used when kamaki is running. Instead, it is aimed to
527 developers who debug or extent the kamaki clients library. For more
528 information, check the
529 `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the
530 `developers section <developers/extending-clients-api.html>`_.