X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/f5f2dc533598070b760bd9c4045ec5a29d8d14e3..6489c38b2e987503dd18e970fe86be8cadfe52a0:/docs/setup.rst diff --git a/docs/setup.rst b/docs/setup.rst index b21860c..43e21a1 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -1,72 +1,305 @@ Setup ===== -Kamaki is easy to install from source or as a package. Some ui features are optional and can be install separately. Kamaki behavior can be configured in the kamaki config file. +Kamaki is easy to install from source or as a package. Some advanced or ui features +are optional and can be installed separately. Kamaki behavior can be configured in +the kamaki config file. Quick Setup ----------- -Kamaki interfaces rely on a list of configuration options. Be default, they are configured to communicate with the `Okeanos IaaS `_. +.. 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. -.. note:: It is essential for users to get a configuration token (okeanos.grnet.gr users go `here `_) and provide it to kamaki: +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 + +Since version 0.14, Synnefo supports a single authentication URL for retrieving +all API endpoints. This URL is retrieved from the Synnefo Web UI and should be +set as the cloud URL for kamaki. All service-specific URLs are retrieved and +handled automatically. Users of Synnefo clouds >=0.14 are advised against using +any service-specific URLs. + +Migrating from kamaki 0.8.X to 0.9 or better +-------------------------------------------- + +This section refers to running installations of kamaki version <= 0.8.X. To +check the current kamaki version: + +.. code-block:: console + + $ kamaki -V + +Existing kamaki users should convert their configuration files to v9. To do +that, kamaki 0.9 can inspect the configuration file and suggests a list of +config file transformations, which are performed automatically after users' +permission. This mechanism is invoked when an API-related kamaki command is +fired. On example 2.1 we suggest using the `user authenticate` command to start +the conversion mechanism for the configuration file. + +.. code-block:: console + :emphasize-lines: 1 + + Example 2.1: Convert config file while authenticating user "exampleuser" + + $ kamaki user authenticate + Config file format version >= 9.0 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 + ... 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 9.0 + 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 anymore. + 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 so that it conforms with the latest version. + +.. 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 1.1: Set user token to myt0k3n== + 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 ommited, kamaki will query the `default` cloud. + +One way to test this, is the `user athenticate` command: + +.. code-block:: console + + $ kamaki --cloud=devel user authenticate + ... + user : + id : 725d5de4-1bab-45ac-9e98-38a60a8c543c + name : Devel User + $ + $ kamaki --cloud=testing user authenticate + ... + user : + id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83 + name : Testing User + $ + $ kamaki --cloud=default user authenticate + ... + user : + id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 + name : Default User + $ + $ kamaki user authenticate + ... + user : + id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 + name : Default User + $ + +In interactive cell, the cloud can be picked when invoking the shell, with +the **- - cloud** option. + +.. code-block:: console + + $ kamaki --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]: - $ kamaki set token myt0k3n== Optional features ----------------- -For installing any all of the following, consult the `kamaki installation guide `_ +For installing any or all of the following, consult the +`kamaki installation guide `_ * ansicolors - * Make command line / console user interface responses prettier with text formating (colors, bold, etc.) - * Can be switched on/off in kamaki configuration file: colors=on/off + * 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 -* progress - * Attach progress bars to various kamaki commands (e.g. kamaki store upload) - * If desired, progress version should be 1.0.2 or better +* 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. +Any of the above features can be installed at any time before or after kamaki +installation. Configuration options --------------------- -Kamaki comes with preset default values to all configuration options. All vital configuration options are set to use the okeanos.grnet.gr cloud services. User information is not included and should be provided either through the kamaki config command or by editing the configuration file. +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-releated configuration +options. Cloud-related information is not included in presets and should be +provided by the user. Kamaki-related options can also be modified. -Kamaki configuration options are vital for correct Kamaki behavior. An incorrect option may render some command groups dysfunctional. There are two ways of managing configuration options: edit the config file or use the kamaki config command. +There are two ways of managing configuration options: edit the config file or +use the kamaki config command. -Using multiple setups -^^^^^^^^^^^^^^^^^^^^^ +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. +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 setups, Kamaki can explicitly load configuration files with the --config option: +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] -Using many different configuration files for different cloud services is encouraged. +.. 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:: +All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example: .. code-block:: console - $ kamaki store list -o global.account=anotheraccount -o global.token=aT0k3n== + $ kamaki file list -o global.pithos_container=anothercontainer -will invoke *kamaki store list* with the specified options, but the initial global.account and global.token values will be restored to initial values afterwards. +will invoke *kamaki file list* with the specified options, but the initial +global.pithos_container values will not be modified. -.. note:: on-the-fly calls to store require users to explicetely provide the account uuid corresponding to this token. The account is actually the uuid field at the response of the following call:: - - $kamaki astakos authenticate aT0k3n== Editing options ^^^^^^^^^^^^^^^ @@ -74,186 +307,237 @@ Editing options Kamaki config command allows users to see and manage all configuration options. * kamaki config list - lists all configuration options currently used by a Kamaki installation + lists all configuration options of a kamaki setup * kamaki config get - show the value of a specific configuration option. Options must be of the form group.option + show the value of a specific configuration option. Options must be of the + form *group.option*. A single *option* is equivalent to *global.option*, + with the exception of the term *cloud* (see bellow) * kamaki config set - set the group.option to value + set the group.option to value. If no group is given, it defaults to + *global*. * kamaki config delete - delete a configuration option + delete a configuration option. If no group is given, it defaults to + *global* The above commands cause option values to be permanently stored in the Kamaki configuration file. +The commands above can also be used for **clouds** handling, using the `cloud.` +prefix. The cloud handling cases are similar but with slightly different +semantics: + +* kamaki config get cloud[.[.option]] + * cloud + list all clouds and their settings + * cloud. + list settings of the cloud aliased as . If no + special is configured, use the term `cloud.default` + * cloud..