Setup ===== Kamaki is easy to install from the official repository or with the pypi mechanism. Quick Setup ----------- .. warning:: Users of kamaki 0.8.X or older should consult the `migration guide <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_ first. To set up Kamaki for a specific Synnefo deployment, users need an **authentication URL** and a **user token**. Users should also pick an alias to name the cloud configuration. This can be any single word, e.g., "default", "mycloud" or whatever suits the user. .. code-block:: console $ kamaki config set cloud..url $ kamaki config set cloud..token myt0k3n== If only one cloud is configured, it is automatically considered the default. Otherwise, a default cloud should be specified: .. code-block:: console $ kamaki config set default_cloud The endpoints (URLs) for each service are resolved automatically from a single URL. This mechanism works for Synnefo v0.14 deployments or later. The authentication URL is retrieved from the Synnefo Web UI and should be set as the cloud URL for kamaki. Users of Synnefo clouds >=0.14 are advised against using any service-specific URLs. Migrating configuration file to latest version ---------------------------------------------- Each new version of kamaki might demand some changes to the configuration file. Kamaki features a mechanism of automatic migration of the configration file to the latest version, which involves heuristics for guessing and translating the file. Quick migration ^^^^^^^^^^^^^^^ The easiest way is to backup and remove the configuration file. The default configuration file location is '${HOME}/.kamakirc'. To reset kamaki, a user needs the authentication URL and TOKEN: .. code-block:: console $ kamaki config set cloud.default.url URL $ kamaki config set cloud.default.token TOKEN After that, a new configuration file will be created. In most cases, this is enough, since kamaki automatically sets the correct options for every functionality. Automatic migration ^^^^^^^^^^^^^^^^^^^ Another way is to let kamaki change the file automatically. Kamaki always inspects the configuration file and, if understood as an older version, it suggests some necessary modifications (user permission is required). On example 2.1 we suggest using the `user info` command to invoke the migration mechanism. .. code-block:: console :emphasize-lines: 1 Example 2.1: Convert config file while authenticating user "exampleuser" $ kamaki user info Config file format version >= 0.12 is required Configuration file: "/home/exampleuser/.kamakirc" but kamaki can fix this: Calculating changes while preserving information ... rescue global.token => cloud.default.token ... rescue config.cli => global.config_cli ... rescue history.file => global.history_file ... change global.network_cli value: `cyclades` => `network` ... DONE The following information will NOT be preserved: global.account = global.data_log = on user.account = exampleuser@example.com user.url = https://accounts.okeanos.grnet.gr compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1 file.url = https://pithos.okeanos.grnet.gr/v1 image.url = https://cyclades.okeanos.grnet.gr/plankton Kamaki is ready to convert the config file to version 0.12 Overwrite file /home/exampleuser/.kamakirc ? [Y, y] At this point, we should examine the kamaki output. Most options are renamed to match the latest configuration file version specifications. Lets take a look at the discarded options: * `global.account` and `user.account` are not used since version 0.9 The same is true for the synonyms `store.account` and `pithos.account`. These options were used to explicitly set a user account or uuid to a pithos call. In the latest Synnefo version (>= 0.14), these features are meaningless and therefore omitted. * `global.data_log` option has never been a valid kamaki config option. In this scenario, the user wanted to set the `log_data` option, but he or she typed `data_log` instead. To fix this, the user should manually set the correct option after the conversion is complete (Example 2.2). Users should press *y* when they are ready, which will cause the default config file to be modified. .. code-block:: console :emphasize-lines: 1 Example 2.2: Rescue misspelled log_data option $ kamaki config set log_data on In order to convert more files, users may run kamaki with the -c option, which runs kamaki with a different configuration file (Example 2.3) and apply the steps described above. .. code-block:: console :emphasize-lines: 1 Example 2.3: Use kamaki to update a configuration file called ".myfilerc" $ kamaki -c .myfilerc user authenticate Multiple clouds --------------- The following refers to users of multiple Synnefo and/or Open Stack deployments. In the following, a Synnefo (or Open Stack) cloud deployment will be called **a cloud**. Multiple clouds can be configured and manager in a single kamaki setup, since version 0.9. Each cloud corresponds to a Synnefo (or Open Stack) cloud deployment, with each deployment offering a single point of authentication (an **authentication URL** and **token** pair). Users can retrieve this information through the cloud UI. Once a user has retrieved one URL/token pair per cloud, it is time to assign a name to each cloud and configure kamaki accordingly. For example, let the user have access to two clouds with the following authentication information :: cloud alias: devel authentication URL: https://devel.example.com/astakos/identity/v2.0/ authentication token: myd3v3170k3n== cloud alias: testing autentication URL: https://testing.example.com/astakos/identity/v2.0/ authentication token: my73571ng70k3n== .. note:: the cloud alias is arbitrary and decided by the user. It is just a reference label for the cloud setup in the kamaki context. The user should let kamaki know about these setups: .. code-block:: console $ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/ $ kamaki config set cloud.devel.token myd3v3170k3n== $ $ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/ $ kamaki config set cloud.testing.token my73571ng70k3n== $ To check if all settings are loaded, a user may list all clouds, as shown bellow: .. code-block:: console $ kamaki config get cloud cloud.default.url = https://example.com/astakos.identity/v2.0/ cloud.default.token = myd3f4u1770k3n== cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/ cloud.devel.token = myd3v3170k3n== cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/ cloud.testing.token = my73571ng70k3n== $ or query kamaki for a specific cloud: .. code-block:: console $ kamaki config get cloud.devel cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/ cloud.devel.token = myd3v3170k3n== $ Now kamaki can use any of these clouds, with the **- - cloud** attribute. If the **- - cloud** option is omitted, kamaki will query the `default` cloud. One way to test this, is the `user info` command: .. code-block:: console $ kamaki --cloud=devel user info ... id : 725d5de4-1bab-45ac-9e98-38a60a8c543c name : Devel User $ $ kamaki --cloud=testing user info ... id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83 name : Testing User $ $ kamaki --cloud=default user info ... id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 name : Default User $ $ kamaki user info ... id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 name : Default User $ In interactive cell, the cloud option should be passed when calling the shell. .. code-block:: console $ kamaki-shell --cloud=devel kamaki v0.10 - Interactive Shell /exit terminate kamaki exit or ^D exit context ? or help available commands ?command help on command ! execute OS shell command Session user is Devel User (uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c) [kamaki]: Optional features ----------------- For installing any or all of the following, consult the `kamaki installation guide `_ * ansicolors * Add colors to command line / console output * Can be switched on/off in kamaki configuration file: `colors = on/off` * Has not been tested on non unix / linux based platforms * mock * For kamaki contributors only * Allow unit tests to run on kamaki.clients package * Needs mock version 1.X or better Any of the above features can be installed at any time before or after kamaki installation. Configuration options --------------------- There are two kinds of configuration options: * kamaki-related (global) interface settings and constants of the kamaki internal mechanism, e.g., terminal colors, maximum threads per connection, custom logging, history file path, etc. * cloud-related information needed to connect and use one or more clouds. There are some mandatory options (URL, token) and some advanced / optional (e.g., service-specific URL overrides or versions) Kamaki comes with preset default values to all kamaki-related configuration options. Cloud-related information is not included in presets and should be provided by the user. Kamaki-related options can also be modified. There are two ways of managing configuration options: edit the config file or use the kamaki config command. Using multiple configuration files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Kamaki setups are stored in configuration files. By default, a Kamaki installation stores options in *.kamakirc* file located at the user home directory. If a user needs to switch between different kamaki-related setups, Kamaki can explicitly load configuration files with the **- - config** (or **- c**) option .. code-block:: console $ kamaki --config [other options] .. note:: For accessing multiple clouds, users do NOT need to create multiple configuration files. Instead, we suggest using a single configuration file with multiple cloud setups. More details can be found at the `multiple clouds guide <#multiple-clouds>`_. Modifying options at runtime ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example: .. code-block:: console $ kamaki file list -o global.pithos_container=anothercontainer will invoke *kamaki file list* with the specified options, but the initial global.pithos_container values will not be modified. Editing options ^^^^^^^^^^^^^^^ Kamaki config command allows users to see and manage all configuration options. * kamaki config list lists all configuration options * kamaki config get [.option] |