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 .. 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.
14 To set up Kamaki for a specific Synnefo deployment, users need an
15 **authentication URL** and a **user token**. Users should also pick an alias to
16 name the cloud configuration. This can be any single word, e.g., "default",
17 "mycloud"or whatever suits the user.
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, it is automatically considered 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. Users of Synnefo clouds >=0.14 are advised against using
35 any service-specific URLs.
37 Migrating from kamaki 0.8.X to 0.9 or better
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 start
52 the conversion mechanism for the configuration file.
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 match the latest configuration file version specifications.
83 Lets 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 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 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.
99 .. code-block:: console
102 Example 2.2: Rescue misspelled log_data option
104 $ kamaki config set log_data on
106 In order to convert more files, users may run kamaki with the -c option, which
107 runs kamaki with a different configuration file (Example 2.3) and apply the
108 steps described above.
110 .. code-block:: console
113 Example 2.3: Use kamaki to update a configuration file called ".myfilerc"
115 $ kamaki -c .myfilerc user authenticate
120 The following refers to users of multiple Synnefo and/or Open Stack
121 deployments. In the following, a Synnefo (or Open Stack) cloud deployment will
122 be called **a cloud**.
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.
130 Once a user has retrieved one URL/token pair per cloud, it is time to assign a
131 name to each cloud and configure kamaki accordingly.
133 For example, let the user have access to two clouds with the following authentication information ::
136 authentication URL: https://devel.example.com/astakos/identity/v2.0/
137 authentication token: myd3v3170k3n==
140 autentication URL: https://testing.example.com/astakos/identity/v2.0/
141 authentication token: my73571ng70k3n==
143 .. note:: the cloud alias is arbitrary and decided by the user. It is just a
144 reference label for the cloud setup in the kamaki context.
146 The user should let kamaki know about these setups:
148 .. code-block:: console
150 $ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/
151 $ kamaki config set cloud.devel.token myd3v3170k3n==
153 $ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/
154 $ kamaki config set cloud.testing.token my73571ng70k3n==
157 To check if all settings are loaded, a user may list all clouds, as shown
160 .. code-block:: console
162 $ kamaki config get cloud
163 cloud.default.url = https://example.com/astakos.identity/v2.0/
164 cloud.default.token = myd3f4u1770k3n==
165 cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
166 cloud.devel.token = myd3v3170k3n==
167 cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/
168 cloud.testing.token = my73571ng70k3n==
171 or query kamaki for a specific cloud:
173 .. code-block:: console
175 $ kamaki config get cloud.devel
176 cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
177 cloud.devel.token = myd3v3170k3n==
180 Now kamaki can use any of these clouds, with the **- - cloud** attribute. If
181 the **- - cloud** option is ommited, kamaki will query the `default` cloud.
183 One way to test this, is the `user athenticate` command:
185 .. code-block:: console
187 $ kamaki --cloud=devel user authenticate
190 id : 725d5de4-1bab-45ac-9e98-38a60a8c543c
193 $ kamaki --cloud=testing user authenticate
196 id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83
199 $ kamaki --cloud=default user authenticate
202 id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
205 $ kamaki user authenticate
208 id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473
212 In interactive cell, the cloud can be picked when invoking the shell, with
213 the **- - cloud** option.
215 .. code-block:: console
217 $ kamaki --cloud=devel
218 kamaki v0.10 - Interactive Shell
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
226 Session user is Devel User
227 (uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c)
234 For installing any or all of the following, consult the
235 `kamaki installation guide <installation.html#install-ansicolors>`_
238 * Add colors to command line / console output
239 * Can be switched on/off in kamaki configuration file: `colors = on/off`
240 * Has not been tested on non unix / linux based platforms
243 * For kamaki contributors only
244 * Allow unit tests to run on kamaki.clients package
245 * Needs mock version 1.X or better
247 Any of the above features can be installed at any time before or after kamaki
250 Configuration options
251 ---------------------
253 There are two kinds of configuration options:
255 * kamaki-related (global)
256 interface settings and constants of the kamaki internal mechanism, e.g.,
257 terminal colors, maximum threads per connection, custom logging, history
261 information needed to connect and use one or more clouds. There are some
262 mandatory options (URL, token) and some advanced / optional (e.g.,
263 service-specific URL overrides or versions)
265 Kamaki comes with preset default values to all kamaki-releated configuration
266 options. Cloud-related information is not included in presets and should be
267 provided by the user. Kamaki-related options can also be modified.
269 There are two ways of managing configuration options: edit the config file or
270 use the kamaki config command.
272 Using multiple configuration files
273 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
275 Kamaki setups are stored in configuration files. By default, a Kamaki
276 installation stores options in *.kamakirc* file located at the user home
279 If a user needs to switch between different kamaki-related setups, Kamaki can
280 explicitly load configuration files with the **- - config** (or **- c**) option
282 .. code-block:: console
284 $ kamaki --config <custom_config_file_path> [other options]
286 .. note:: For accessing multiple clouds, users do NOT need to create multiple
287 configuration files. Instead, we suggest using a single configuration file
288 with multiple cloud setups. More details can be found at the
289 `multiple clouds guide <#multiple-clouds>`_.
291 Modifying options at runtime
292 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
294 All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example:
296 .. code-block:: console
298 $ kamaki file list -o global.pithos_container=anothercontainer
300 will invoke *kamaki file list* with the specified options, but the initial
301 global.pithos_container values will not be modified.
307 Kamaki config command allows users to see and manage all configuration options.
310 lists all configuration options of a kamaki setup
312 * kamaki config get <group.option>
313 show the value of a specific configuration option. Options must be of the
314 form *group.option*. A single *option* is equivalent to *global.option*,
315 with the exception of the term *cloud* (see bellow)
317 * kamaki config set <group.option> <value>
318 set the group.option to value. If no group is given, it defaults to
321 * kamaki config delete <group.option>
322 delete a configuration option. If no group is given, it defaults to
325 The above commands cause option values to be permanently stored in the Kamaki configuration file.
327 The commands above can also be used for **clouds** handling, using the `cloud.`
328 prefix. The cloud handling cases are similar but with slightly different
331 * kamaki config get cloud[.<cloud alias>[.option]]
333 list all clouds and their settings
334 * cloud.<cloud alias>
335 list settings of the cloud aliased as <cloud alias>. If no
336 special is configured, use the term `cloud.default`
337 * cloud.<cloud alias>.<option>
338 show the value of the specified option. If no special alias is
339 configured, use `cloud.default.<option>`
341 * kamaki config set cloud.<cloud alias>.<option> <value>
342 If the cloud alias <cloud alias> does not exist, create it. Then, create
343 (or update) the option <option> of this cloud, by setting its value
346 * kamaki config delete cloud.<cloud alias>[.<option>]
347 * cloud.<cloud alias>
348 delete the cloud alias <cloud alias> and all its options
349 * cloud.<cloud alias>.<option>
350 delete the <option> and its value from the cloud cloud aliased as
353 To see if a default cloud is configured, get the default_cloud value
355 .. code-block:: console
357 $ kamaki config get default_cloud
359 If no default_cloud value is set, the first cloud alias is picked as default.
360 To pick a cloud alias as default:
362 .. code-block:: console
364 $ kamaki config set default_cloud <cloud alias>
367 Editing the configuration file
368 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
370 The configuration file is a simple text file that can be created by the user.
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>`_
377 A simple way to create the configuration file is to set a configuration option
378 using the kamaki config command. For example:
380 .. code-block:: console
382 $ kamaki config set global.log_file /home/exampleuser/logs/kamaki.log
384 In the above example, if the kamaki configuration file does not exist, it will
385 be created with all the default values plus the *global.log_file* option set to
386 `/home/exampleuser/logs/kamaki.log`
388 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::
391 log_file = /home/exampleuser/logs/kamaki.log
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
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.
410 The [*global*] group is treated by kamaki as a generic group for kamaki
411 settings, namely command cli specifications, the thread limit, console colors,
412 history and log files, log detail options and pithos-specific options.
414 * global.colors <on|off>
415 enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored
417 * global.log_file <logfile full path>
418 set a custom location for kamaki logging. Default value is ~/.kamaki.log
420 * global.log_token <on|off>
421 allow kamaki to log user tokens
423 * global.log_data <on|off>
424 allow kamaki to log http data (by default, it logs only method, URL and
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.
431 * global.file_cli <UI command specifications for file>
432 a special package that is used to load storage commands to kamaki UIs.
433 Don't touch this unless if you know what you are doing.
435 * global.cyclades_cli <UI command specifications for cyclades>
436 a special package that is used to load cyclades commands to kamaki UIs.
437 Don't touch this unless you know what you are doing.
439 * global.flavor_cli <UI command specifications for VM flavors>
440 a special package that is used to load cyclades VM flavor commands to
441 kamaki UIs. Don't touch this unless you know what you are doing.
443 * global.network_cli <UI command specifications for virtual networks>
444 a special package that is used to load cyclades virtual network commands to
445 kamaki UIs. Don't touch this unless you know what you are doing.
447 * global.image_cli <UI command specs for Plankton or Compute image service>
448 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.
450 * global.user_cli <UI command specs for Astakos authentication service>
451 a special package that is used to load astakos-related commands to kamaki
452 UIs. Don't touch this unless you know what you are doing.
454 * global.history_file <history file path>
455 the path of a simple file for inter-session kamaki history. Make sure
456 kamaki is executed in a context where this file is accessible for reading
457 and writing. Kamaki automatically creates the file if it doesn't exist
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* .
470 The livetest commands can be activated by setting the following option in the
474 livetest_cli=livetest
476 or with this kamaki command::
478 $ kamaki config set livetest_cli livetest
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.
484 Here is a list of settings needed:
487 * livetest.testcloud = <the cloud alias this test will run against>
489 * for astakos client::
490 * livetest.astakos_details = <A file with an authentication output>
491 To create this file, pipeline the output of an authentication command
492 with the -j option for raw json output
494 .. code-block:: console
496 $ kamaki user authenticate -j > astakos.details
498 * livetest.astakos_name = <The exact "real" name of the testing user>
499 * livetest.astakos_id = <The valid unique user id of the testing user>
502 * livetest.image_details = <A file with the image metadata>
503 To create this file, pipeline the output of an image metadata command
504 with the -j option for raw json output
506 .. code-block:: console
508 $ kamaki image info <img id> -j > img.details
510 * livetest.image_id = <A valid image id used for testing>
511 * livetest.image_local_path = <The local path of the testing image>
513 * for flavors (part of the compute client):
514 * livetest.flavor_details = <A file with the flavor details>
515 To create this file, pipeline the output of a flavor info command
516 with the -j option for raw json output
518 .. code-block:: console
520 $ kamaki flavor info <flavor id> -j > flavor.details
523 After setup, kamaki can run all tests::
525 $ kamaki livetest all
527 a specific test (e.g., pithos scenario)::
529 $ kamaki livetest pithos
531 or a specific method from a service (e.g., create_server @ cyclades)::
533 $ kamaki livetest cyclades create_server
536 The unit testing system
537 """""""""""""""""""""""
539 Kamaki container a set of finegrained unit tests for the kamaki.clients
540 package. This set is not used when kamaki is running. Instead, it is aimed to
541 developers who debug or extent kamaki. For more information, check the
542 `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the
543 `developers section <developers/extending-clients-api.html>`_.