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 version 0.14, Synnefo supports a single authentication URL for retrieving
32 all API endpoints. This URL is retrieved from the Synnefo Web UI and should be
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.
37 Migrating from kamaki 0.8.X to 0.9
38 ----------------------------------
40 This section refers to running installations of kamaki version <= 0.8.X. To
41 check the current kamaki version:
43 .. code-block:: console
47 Existing kamaki users should convert their configuration files to v9. To do
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.
54 .. code-block:: console
57 Example 2.1: Convert config file while authenticating user "exampleuser"
59 $ kamaki user authenticate
60 Config file format version >= 9.0 is required
61 Configuration file: "/home/exampleuser/.kamakirc"
62 but kamaki can fix this:
63 Calculating changes while preserving information
64 ... rescue global.token => cloud.default.token
65 ... rescue config.cli => global.config_cli
66 ... rescue history.file => global.history_file
68 The following information will NOT be preserved:
71 user.account = exampleuser@example.com
72 user.url = https://accounts.okeanos.grnet.gr
73 compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1
74 file.url = https://pithos.okeanos.grnet.gr/v1
75 image.url = https://cyclades.okeanos.grnet.gr/plankton
77 Kamaki is ready to convert the config file to version 9.0
78 Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
80 At this point, we should examine the kamaki output. Most options are renamed to
81 be understood by the new kamaki.
83 Let's take a look at the discarded options:
85 * `global.account` and `user.account` are not used anymore.
86 The same is true for the synonyms `store.account` and `pithos.account`.
87 These options were used to explicitly set a user account or uuid to a
88 pithos call. In the latest Synnefo version (>= 0.14), these features are
89 meaningless and therefore omitted.
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
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).
101 .. code-block:: console
104 Example 2.2: Rescue misspelled log_data option
106 $ kamaki config set log_data on
108 In order to convert more files, users may run kamaki with the -c option, which
109 runs kamaki with a different configuration file (Example 2.3) and apply the
110 steps described above.
112 .. code-block:: console
115 Example 2.3: Use kamaki to update a configuration file called ".myfilerc"
117 $ kamaki -c .myfilerc user authenticate
122 The following refers to users of multiple Synnefo and/or Open Stack
123 deployments. In the following, a Synnefo or Open Stack cloud deployment will
124 frequently be called as a **cloud**.
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.
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.
135 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.
138 For example, let the user have access to two clouds with the following authentication information ::
141 authentication URL: https://devel.example.com/astakos/identity/v2.0/
142 authentication token: myd3v3170k3n==
145 autentication URL: https://testing.example.com/astakos/identity/v2.0/
146 authentication token: my73571ng70k3n==
148 .. 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.
151 The user should let kamaki know about these setups:
153 .. code-block:: console
155 $ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/
156 $ kamaki config set cloud.devel.token myd3v3170k3n==
158 $ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/
159 $ kamaki config set cloud.testing.token my73571ng70k3n==
162 To check if all settings are loaded, a user may list all clouds, as shown
165 .. code-block:: console
167 $ kamaki config getcloud
168 cloud.default.url = https://example.com/astakos.identity/v2.0/
169 cloud.default.url = myd3f4u1770k3n==
170 cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
171 cloud.devel.token = myd3v3170k3n==
172 cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/
173 cloud.testing.token = my73571ng70k3n==
176 or query kamaki for a specific cloud:
178 .. code-block:: console
180 $ kamaki config get cloud.devel
181 cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
182 cloud.devel.token = myd3v3170k3n==
185 Now kamaki can use any of these clouds, with the **- - cloud** attribute. If
186 the **- - cloud** option is ommited, kamaki will query the `default` cloud.
188 One way to test this, is the `user athenticate` command:
190 .. code-block:: console
192 $ kamaki --cloud=devel user authenticate
195 id : 725d5de4-1bab-45ac-9e98-38a60a8c543c
198 $ kamaki --cloud=testing user authenticate
201 id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83
204 $ kamaki --cloud=default user authenticate
207 id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
210 $ kamaki user authenticate
213 id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
217 In interactive cell, the cloud is picked when invoking the shell, with
218 the **- - cloud** option.
223 For installing any or all of the following, consult the
224 `kamaki installation guide <installation.html#install-ansicolors>`_
227 * Add colors to command line / console output
228 * Can be switched on/off in kamaki configuration file: `colors = on/off`
229 * Has not been tested on non unix / linux based platforms
232 * For kamaki contributors only
233 * Allow unit tests to run on kamaki.clients package
234 * Needs mock version 1.X or better
237 * For advanced users mostly
238 * Allows the use of a full astakos command line client
240 Any of the above features can be installed at any time before or after kamaki
243 Configuration options
244 ---------------------
246 There are two kinds of configuration options:
248 * kamaki-related (global)
249 interface settings and constants of the kamaki internal mechanism, e.g.,
250 colors in the output, maximum threads per connection, custom logging or
254 information needed to connect and use one or more clouds. There are some
255 mandatory options (URL, token) and some advanced / optional (e.g.,
256 service-specific URL overrides or versions)
258 Kamaki comes with preset default values to all kamaki-releated configuration
259 options. Cloud-related information is not included in presets and should be
260 provided by the user. Kamaki-related options can also be modified.
262 There are two ways of managing configuration options: edit the config file or
263 use the kamaki config command.
265 Using multiple configuration files
266 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
268 Kamaki setups are stored in configuration files. By default, a Kamaki
269 installation stores options in *.kamakirc* file located at the user home
272 If a user needs to switch between different kamaki-related setups, Kamaki can
273 explicitly load configuration files with the **- - config** (or **- c**) option
275 .. code-block:: console
277 $ kamaki --config <custom_config_file_path> [other options]
279 .. note:: For accessing multiple clouds, users do NOT need to create multiple
280 configuration files. Instead, we suggest using a single configuration file
281 with multiple cloud setups. More details can be found at the
282 `multiple clouds guide <#multiple-clouds>`_.
284 Modifying options at runtime
285 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
287 All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
289 .. code-block:: console
291 $ kamaki file list -o global.pithos_container=anothercontainer
293 will invoke *kamaki file list* with the specified options, but the initial
294 global.pithos_container values will not be modified.
299 Kamaki config command allows users to see and manage all configuration options.
302 lists all configuration options currently used by a Kamaki installation
304 * kamaki config get <group.option>
305 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*
308 * kamaki config set <group.option> <value>
309 set the group.option to value. If no group is given, the defaults to
312 * kamaki config delete <group.option>
313 delete a configuration option. If no group is given, the defaults to
316 The above commands cause option values to be permanently stored in the Kamaki configuration file.
318 The commands above can also be used for **clouds** handling, using the `cloud.`
319 prefix. The cloud handling cases are similar but with slightly different
322 * kamaki config get cloud[.<cloud alias>[.option]]
324 list all clouds and their settings
325 * cloud.<cloud alias>
326 list settings of the cloud aliased as <cloud alias>. If no
327 special is configured, use the term `cloud.default`
328 * cloud.<cloud alias>.<option>
329 show the value of the specified option. If no special alias is
330 configured, use `cloud.default.<option>`
332 * kamaki config set cloud.<cloud alias>.<option> <value>
333 If the cloud alias <cloud alias> does not exist, create it. Then, create
334 (or update) the option <option> of this cloud, by setting its value
337 * kamaki config delete cloud.<cloud alias>[.<option>]
338 * cloud.<cloud alias>
339 delete the cloud alias <cloud alias> and all its options
340 * cloud.<cloud alias>.<option>
341 delete the <option> and its value from the cloud cloud aliased as
344 .. note:: To see if a default cloud is configured, get the default_cloud value
346 .. code-block:: console
348 $ kamaki config get default_cloud
350 Editing the configuration file
351 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
353 The configuration file is a simple text file that can be created by the user.
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>`_
359 A simple way to create the configuration file is to set a configuration option
360 using the kamaki config command. For example:
362 .. code-block:: console
364 $ kamaki config set global.log_file /home/exampleuser/logs/kamaki.log
366 In the above example, if the kamaki configuration file does not exist, it will
367 be created with all the default values plus the *global.log_file* option set to
368 `/home/exampleuser/logs/kamaki.log`
370 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::
373 log_file = /home/exampleuser/logs/kamaki.log
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.
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.
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>`_ ::
392 url = https://devel.example.com/astakos/identity/v2.0/
393 token = myd3v3170k3n==
396 url = https://testing.example.com/astakos/identity/v2.0/
397 token = my73571ng70k3n==
402 The [global] group is treated by kamaki as a generic group for kamaki-related
403 settings, namely command cli specifications, the thread limit, console colors,
404 history and log files, log detail options and pithos-specific options.
406 * global.colors <on|off>
407 enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored
409 * global.log_file <logfile full path>
410 set a custom location for kamaki logging. Default value is ~/.kamaki.log
412 * global.log_token <on|off>
413 allow kamaki to log user tokens
415 * global.log_data <on|off>
416 allow kamaki to log http data (by default, it logs only method, URL and
419 * global.file_cli <UI command specifications for file>
420 a special package that is used to load storage commands to kamaki UIs.
421 Don't touch this unless if you know what you are doing.
423 * global.cyclades_cli <UI command specifications for cyclades>
424 a special package that is used to load cyclades commands to kamaki UIs.
425 Don't touch this unless you know what you are doing.
427 * global.flavor_cli <UI command specifications for VM flavors>
428 a special package that is used to load cyclades VM flavor commands to
429 kamaki UIs. Don't touch this unless you know what you are doing.
431 * global.network_cli <UI command specifications for virtual networks>
432 a special package that is used to load cyclades virtual network commands to
433 kamaki UIs. Don't touch this unless you know what you are doing.
435 * global.image_cli <UI command specs for Plankton or Compute image service>
436 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.
438 * global.user_cli <UI command specs for Astakos authentication service>
439 a special package that is used to load astakos-related commands to kamaki
440 UIs. Don't touch this unless you know what you are doing.
442 * global.history_file <history file path>
443 the path of a simple file for inter-session kamaki history. Make sure
444 kamaki is executed in a context where this file is accessible for reading
445 and writing. Kamaki automatically creates the file if it doesn't exist
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
459 The livetest suite can be activated with the following option on the configuration file::
462 livetest_cli=livetest
464 or with this kamaki command::
466 kamaki config set livetest_cli livetest
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.
472 Here is a list of settings needed:
475 * livetest.testcloud = <the cloud alias this test will run against>
477 * for astakos client::
478 * livetest.astakos_details = <A file with an authentication output>
479 To create this file, pipeline the output of an authentication command
480 with the -j option for raw jason output
482 .. code-block:: console
484 $ kamaki user authenticate -j > astakos.details
486 * livetest.astakos_name = <The exact "real" name of testing user>
487 * livetest.astakos_id = <The valid unique user id of the testing user>
490 * livetest.image_details = <A file with the image's metadata>
491 To create this file, pipeline the output of an image metadata command
492 with the -j option for raw jason output
494 .. code-block:: console
496 $ kamaki image info <img id> -j > img.details
498 * livetest.image_id = <A valid image id used for testing>
499 * livetest.image_local_path = <The local path of the testing image>
501 * for flavors (part of the compute client):
502 * livetest.flavor_details = <A file with the flavor details>
503 To create this file, pipeline the output of a flavor info command
504 with the -j option for raw jason output
506 .. code-block:: console
508 $ kamaki flavor info <flavor id> -j > flavor.details
511 After setup, kamaki can run all tests::
513 $ kamaki livetest all
515 a specific test (e.g., astakos)::
517 $ kamaki livetest astakos
519 or a specific method from a service (e.g., astakos authenticate)::
521 $ kamaki livetest astakos authenticate
523 The unit testing system
524 """""""""""""""""""""""
526 Kamaki container a set of finegrained unit tests for the kamaki.clients
527 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
530 `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the
531 `developers section <developers/extending-clients-api.html>`_.