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

   1 Set up
   2 ======
   3
   4 Kamaki is easy to install from source or as a package. Some ui features are optional and can be install seperately. Kamaki behavior can be configured in the kamaki config file.
   5
   6 Requirements
   7 ------------
   8
   9 * python 2.6 or better
  10
  11 * snf-common 0.10 or better
  12
  13 The snf-common package is part of the Synnefo project of the Greek Research and Development Network and is available from the same official sources as Kamaki (e.g. http://apt.dev.grnet.gr ).
  14
  15 Optional features
  16 -----------------
  17
  18 * ansicolors
  19     * Make command line / console user interface responses pretier with text formating (colors, bold, etc.)
  20     * Can be switched on/off in kamaki configuration file: colors=on/off
  21     * Installation: pip install ansicolors
  22
  23 * progressbar
  24     * Attach progressbars to various kamaki commands (e.g. kamaki store upload)
  25     * Installation: pip install progressbar
  26
  27 Any of the above features can be installed at any time before or after kamaki installation.
  28
  29 Configuration options
  30 ---------------------
  31
  32 Kamaki comes with preset default values to all configuration options. All vital configurion 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.
  33
  34 Kamaki configuration options are vital for correct Kamaki behavior. An incorrect option may render some command groups disfunctional. There are two ways of managing configuration options: edit the config file or use the kamaki config command.
  35
  36 Using multiple setups
  37 ^^^^^^^^^^^^^^^^^^^^^
  38
  39 Kamaki setups are stored in configuration files. By default, a Kamaki installation stores options in *.kamakirc* file located at the user home directory.
  40
  41 If a user needs to switch between different setups, Kamaki can explicitely load configuration files with the --config option:
  42
  43 *kamaki --config <custom_config_file_path> [other options]*
  44
  45 Using many different configuration files for different cloud services is encouraged.
  46
  47 Modifying options at runtime
  48 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  49
  50 All kamaki commands can be used with the -o option in order to overide configuration options at runtime. For example:
  51
  52 *kamaki store list -o global.account=anotheraccount -o global.token=aT0k3n==*
  53
  54 will call *kamaki store list* with the specified options, but the initial global.account and global.token values will be restored afterwards.
  55
  56 Editing options
  57 ^^^^^^^^^^^^^^^
  58
  59 Kamaki config command allows users to see and manage all configuration options.
  60
  61 * kamaki config list
  62     lists all configuration options currently used by a Kamaki installation
  63
  64 * kamaki config get <group.option>
  65     show the value of a specific configuration option. Options must be of the form group.option
  66
  67 * kamaki config set <group.option> <value>
  68     set the group.option to value
  69
  70 *kamaki config delete <group.option>
  71     delete a configuration option
  72
  73 The above commands cause option values to be permanently stored in the Kamaki configuration file.
  74
  75 Editing the configuration file
  76 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  77
  78 The configuration file is a simple text file that can be created by the user.d
  79
  80 A simple way to create the configuration file is to set a configuration option using the kamaki config command. For example:
  81
  82 *kamaki config set account myusername@mydomain.com*
  83
  84 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.
  85
  86 The configuration file is formated so that it can be parsed by the python Config Parser module. It consists of command sections that are denoted with brackets. Every section contains variables with values. For example:
  87
  88 *[store]*
  89 *url=https://okeanos.grnet.gr/pithos*
  90 *account=myaccount@mydomain.com*
  91
  92 two configuration options are created: *store.url* and *store.account*. These values will be loaded at every future kamaki execution.
  93
  94 Available options
  95 ^^^^^^^^^^^^^^^^^
  96
  97 The [global] group is treated by kamaki as a generic group for arbitary options, and it is used as a super-group for vital Kamaki options like account, token, or url. 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 overide the global ones.
  98
  99 * global.colors <on|off>
 100     enable/dissable colors in command line based uis. Requires ansicolors, otherwise it is ignored
 101
 102 * global.account <account name>
 103     the username or user email that is user to connect to the cloud service. It can be ommited if provided as a service-specific option
 104
 105 * global.token <user authedication token>
 106
 107 * store.cli <UI command specifications for store>
 108     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.
 109
 110 * store.url <OOS storage or Pithos+ service url>
 111     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.
 112
 113 * store.account <account name>
 114     if set, it overides possible global.account option for store level commands.
 115
 116 * compute.url <OOS compute or Cyclades service url>
 117     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.
 118
 119 * cyclades.cli <UI command specifications for cyclades>
 120     a special package that is used to load cyclades commands to kamaki UIs. Don't touch this unless you know what you are doing.
 121
 122 * flavor.cli <UI command specifications for VM flavors>
 123     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.
 124
 125 * network.cli <UI command specifications for virtual networks>
 126     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.
 127
 128 * image.url <Glance image service url>
 129     the url of the Glance service. Set to Okeanos.grnet.gr Plankton service be default. Users should set a different value if they need to use a different service.
 130
 131 * image.cli <UI command specifications for Glance and Cyclades image service>
 132     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.
 133
 134 * astakos.url <Astakos authentication service url>
 135     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.
 136
 137 * astakos.cli <UI command specifications for Astakos authentication service>
 138     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.