code.grnet.gr Git - kamaki/blob - docs/setup.rst

   1 Setup
   2 =====
   3
   4 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.
   5
   6 Quick Setup
   7 -----------
   8
   9 Kamaki interfaces rely on a list of configuration options. Be default, they are configured to communicate with the `Okeanos IaaS <http://okeanos.grnet.gr>`_.
  10
  11 .. note:: It is essential for users to get a configuration token (okeanos.grnet.gr users go `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
  12
  13
  14 .. code-block:: console
  15     :emphasize-lines: 1
  16
  17     Example 1.1: Set user token to myt0k3n==
  18
  19     $ kamaki set token myt0k3n==
  20
  21 To use the storage service, a user should also provide the corresponding user-name:
  22
  23 .. code-block:: console
  24     :emphasize-lines: 1
  25
  26     Example 1.2: Set user name to user@domain.com
  27
  28     $ kamaki set store.account user@domain.com
  29
  30 Optional features
  31 -----------------
  32
  33 For installing any all of the following, consult the `kamaki installation guide <installation.html#install-progress-and-or-ansicolors-optional>`_
  34
  35 * ansicolors
  36     * Make command line / console user interface responses prettier with text formating (colors, bold, etc.)
  37     * Can be switched on/off in kamaki configuration file: colors=on/off
  38
  39 * progress
  40     * Attach progress bars to various kamaki commands (e.g. kamaki store upload)
  41     * Since version 0.6.1 kamaki "requires" progress version 1.0.2 or better
  42
  43 Any of the above features can be installed at any time before or after kamaki installation.
  44
  45 Configuration options
  46 ---------------------
  47
  48 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.
  49
  50 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.
  51
  52 Using multiple setups
  53 ^^^^^^^^^^^^^^^^^^^^^
  54
  55 Kamaki setups are stored in configuration files. By default, a Kamaki installation stores options in *.kamakirc* file located at the user home directory.
  56
  57 If a user needs to switch between different setups, Kamaki can explicitly load configuration files with the --config option:
  58
  59 .. code-block:: console
  60
  61     $ kamaki --config <custom_config_file_path> [other options]
  62
  63 Using many different configuration files for different cloud services is encouraged.
  64
  65 Modifying options at runtime
  66 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  67
  68 All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
  69
  70 .. code-block:: console
  71
  72     $ kamaki store list -o global.account=anotheraccount -o global.token=aT0k3n==
  73
  74 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.
  75
  76 Editing options
  77 ^^^^^^^^^^^^^^^
  78
  79 Kamaki config command allows users to see and manage all configuration options.
  80
  81 * kamaki config list
  82     lists all configuration options currently used by a Kamaki installation
  83
  84 * kamaki config get <group.option>
  85     show the value of a specific configuration option. Options must be of the form group.option
  86
  87 * kamaki config set <group.option> <value>
  88     set the group.option to value
  89
  90 * kamaki config delete <group.option>
  91     delete a configuration option
  92
  93 The above commands cause option values to be permanently stored in the Kamaki configuration file.
  94
  95 Editing the configuration file
  96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  97
  98 The configuration file is a simple text file that can be created by the user.
  99
 100 A simple way to create the configuration file is to set a configuration option using the kamaki config command. For example:
 101
 102 .. code-block:: console
 103
 104     $ kamaki config set account myusername@mydomain.com
 105
 106 In the above example, if the kamaki configuration file does not exist, it will be created with all the default values plus the *global.account* option set to *myusername@mydomain.com* value.
 107
 108 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::
 109
 110     [store]
 111     url=https://okeanos.grnet.gr/pithos
 112     account=myaccount@mydomain.com
 113
 114 two configuration options are created: *store.url* and *store.account*. These values will be loaded at every future kamaki execution.
 115
 116 Available options
 117 ^^^^^^^^^^^^^^^^^
 118
 119 The [global] group is treated by kamaki as a generic group for arbitrary options, and it is used as a super-group for vital Kamaki options, namely account, token, url, cli. This feature does not work for types of configuration options. For example if global.account option is set and store.account option is not set, store services will use the global.account option instead. In case of conflict, the most specific options override the global ones.
 120
 121 * global.colors <on|off>
 122     enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored
 123
 124 * global.account <account name>
 125     the username or user email that is user to connect to the cloud service. It can be omitted if provided as a service-specific option
 126
 127 * global.token <user authentication token>
 128
 129 * store.cli <UI command specifications for store>
 130     a special package that is used to load storage commands to kamaki UIs. Don't touch this unless if you know what you are doing.
 131
 132 * store.url <OOS storage or Pithos+ service url>
 133     the url of the OOS storage or Pithos+ service. Set to Okeanos.grnet.gr Pithos+ storage service by default. Users should set a different value if they need to use a different storage service.
 134
 135 * store.account <account name>
 136     if set, it overrides possible global.account option for store level commands.
 137
 138 * store.token <token>
 139     it set, it overrides possible global.token option for store level commands
 140
 141 * compute.url <OOS compute or Cyclades service url>
 142     the url of the OOS compute or Cyclades service. Set to Okeanos.grnet.gr Cyclades IaaS service by default. Users should set a different value if they need to use a different IaaS service.
 143
 144 * cyclades.cli <UI command specifications for cyclades>
 145     a special package that is used to load cyclades commands to kamaki UIs. Don't touch this unless you know what you are doing.
 146
 147 * flavor.cli <UI command specifications for VM flavors>
 148     a special package that is used to load cyclades VM flavor commands to kamaki UIs. Don't touch this unless you know what you are doing.
 149
 150 * network.cli <UI command specifications for virtual networks>
 151     a special package that is used to load cyclades virtual network commands to kamaki UIs. Don't touch this unless you know what you are doing.
 152
 153 * image.url <Plankton image service url>
 154     the url of the Plankton service. Set to Okeanos.grnet.gr Plankton service be default. Users should set a different value if they need to use a different service.
 155
 156 * image.cli <UI command specifications for Plankton and Cyclades image service>
 157     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.
 158
 159 * astakos.url <Astakos authentication service url>
 160     the url of the Astakos authentication service. Set to the Okeanos.grnet.gr Astakos service by default. Users should set a different value if they need to use a different service.
 161
 162 * astakos.cli <UI command specifications for Astakos authentication service>
 163     a special package that is used to load astakos-related commands to kamaki UIs. Don't touch this unless you know what you are doing.
 164
 165 * history.file <history file path>
 166     the path of a simple file for inter-session kamaki history. Make sure kamaki is executed in a context where this file is accessible for reading and writing. Kamaki automatically creates the file if it doesn't exist
 167
 168 Hidden features
 169 ^^^^^^^^^^^^^^^
 170
 171 Since version 0.6.1 kamaki contains a test suite for the kamaki.clients API. The test suite can be activated with the following option on the configuration file::
 172
 173     [test]
 174     cli=test_cli
 175
 176 After that, users can run "kamaki test" commands to unit-test the prepackaged client APIs. Unit-tests are still experimental and there is a high probability of false alarms due to some of the expected values being hard-coded in the testing code.
 177
 178 In version 0.6.3, a quotaholder client is introduced as an advanced feature. Quotaholder client is mostly used as a client library for accessing a synnefo quota service, but it can also be allowed as a kamaki command set, but setting the quotaholder.cli and quotaholder.url methods:
 179
 180     [quotaholder]
 181     cli=quotaholder_cli
 182     url=<URL of quotaholder service>