root / docs / setup.rst @ f5f2dc53
History | View | Annotate | Download (10.8 kB)
1 | 85e3803d | Stavros Sachtouris | Setup |
---|---|---|---|
2 | 85e3803d | Stavros Sachtouris | ===== |
3 | 0c24b26b | Stavros Sachtouris | |
4 | 85e3803d | Stavros Sachtouris | 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 | 0c24b26b | Stavros Sachtouris | |
6 | c52d1b08 | Stavros Sachtouris | Quick Setup |
7 | c52d1b08 | Stavros Sachtouris | ----------- |
8 | c52d1b08 | Stavros Sachtouris | |
9 | c52d1b08 | Stavros Sachtouris | 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 | c52d1b08 | Stavros Sachtouris | |
11 | c52d1b08 | Stavros Sachtouris | .. 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 | c52d1b08 | Stavros Sachtouris | |
13 | d6737e18 | Stavros Sachtouris | |
14 | c52d1b08 | Stavros Sachtouris | .. code-block:: console |
15 | c52d1b08 | Stavros Sachtouris | :emphasize-lines: 1 |
16 | c52d1b08 | Stavros Sachtouris | |
17 | c52d1b08 | Stavros Sachtouris | Example 1.1: Set user token to myt0k3n== |
18 | c52d1b08 | Stavros Sachtouris | |
19 | c52d1b08 | Stavros Sachtouris | $ kamaki set token myt0k3n== |
20 | c52d1b08 | Stavros Sachtouris | |
21 | 0c24b26b | Stavros Sachtouris | Optional features |
22 | 0c24b26b | Stavros Sachtouris | ----------------- |
23 | 0c24b26b | Stavros Sachtouris | |
24 | 961e6040 | Stavros Sachtouris | For installing any all of the following, consult the `kamaki installation guide <installation.html#install-progress-and-or-ansicolors-optional>`_ |
25 | 961e6040 | Stavros Sachtouris | |
26 | 0c24b26b | Stavros Sachtouris | * ansicolors |
27 | 7536c9bf | Stavros Sachtouris | * Make command line / console user interface responses prettier with text formating (colors, bold, etc.) |
28 | 0c24b26b | Stavros Sachtouris | * Can be switched on/off in kamaki configuration file: colors=on/off |
29 | 0c24b26b | Stavros Sachtouris | |
30 | 329753ae | Stavros Sachtouris | * progress |
31 | 329753ae | Stavros Sachtouris | * Attach progress bars to various kamaki commands (e.g. kamaki store upload) |
32 | f5f2dc53 | Stavros Sachtouris | * If desired, progress version should be 1.0.2 or better |
33 | 0c24b26b | Stavros Sachtouris | |
34 | 0c24b26b | Stavros Sachtouris | Any of the above features can be installed at any time before or after kamaki installation. |
35 | 0c24b26b | Stavros Sachtouris | |
36 | 0c24b26b | Stavros Sachtouris | Configuration options |
37 | 0c24b26b | Stavros Sachtouris | --------------------- |
38 | 0c24b26b | Stavros Sachtouris | |
39 | 7536c9bf | Stavros Sachtouris | 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. |
40 | 0c24b26b | Stavros Sachtouris | |
41 | 85e3803d | Stavros Sachtouris | 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. |
42 | 0c24b26b | Stavros Sachtouris | |
43 | 0c24b26b | Stavros Sachtouris | Using multiple setups |
44 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^ |
45 | 0c24b26b | Stavros Sachtouris | |
46 | 0c24b26b | Stavros Sachtouris | Kamaki setups are stored in configuration files. By default, a Kamaki installation stores options in *.kamakirc* file located at the user home directory. |
47 | 0c24b26b | Stavros Sachtouris | |
48 | 7536c9bf | Stavros Sachtouris | If a user needs to switch between different setups, Kamaki can explicitly load configuration files with the --config option: |
49 | 0c24b26b | Stavros Sachtouris | |
50 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
51 | 03d661d8 | Stavros Sachtouris | |
52 | 03d661d8 | Stavros Sachtouris | $ kamaki --config <custom_config_file_path> [other options] |
53 | 0c24b26b | Stavros Sachtouris | |
54 | 0c24b26b | Stavros Sachtouris | Using many different configuration files for different cloud services is encouraged. |
55 | 0c24b26b | Stavros Sachtouris | |
56 | 0c24b26b | Stavros Sachtouris | Modifying options at runtime |
57 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
58 | 0c24b26b | Stavros Sachtouris | |
59 | 7536c9bf | Stavros Sachtouris | All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example:: |
60 | 0c24b26b | Stavros Sachtouris | |
61 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
62 | 03d661d8 | Stavros Sachtouris | |
63 | 03d661d8 | Stavros Sachtouris | $ kamaki store list -o global.account=anotheraccount -o global.token=aT0k3n== |
64 | 0c24b26b | Stavros Sachtouris | |
65 | 329753ae | Stavros Sachtouris | 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. |
66 | 0c24b26b | Stavros Sachtouris | |
67 | 7ae842c2 | Stavros Sachtouris | .. 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:: |
68 | 7ae842c2 | Stavros Sachtouris | |
69 | 7ae842c2 | Stavros Sachtouris | $kamaki astakos authenticate aT0k3n== |
70 | 7ae842c2 | Stavros Sachtouris | |
71 | 0c24b26b | Stavros Sachtouris | Editing options |
72 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^ |
73 | 0c24b26b | Stavros Sachtouris | |
74 | 0c24b26b | Stavros Sachtouris | Kamaki config command allows users to see and manage all configuration options. |
75 | 0c24b26b | Stavros Sachtouris | |
76 | 0c24b26b | Stavros Sachtouris | * kamaki config list |
77 | 0c24b26b | Stavros Sachtouris | lists all configuration options currently used by a Kamaki installation |
78 | 0c24b26b | Stavros Sachtouris | |
79 | 0c24b26b | Stavros Sachtouris | * kamaki config get <group.option> |
80 | 0c24b26b | Stavros Sachtouris | show the value of a specific configuration option. Options must be of the form group.option |
81 | 0c24b26b | Stavros Sachtouris | |
82 | 0c24b26b | Stavros Sachtouris | * kamaki config set <group.option> <value> |
83 | 0c24b26b | Stavros Sachtouris | set the group.option to value |
84 | 0c24b26b | Stavros Sachtouris | |
85 | 329753ae | Stavros Sachtouris | * kamaki config delete <group.option> |
86 | 0c24b26b | Stavros Sachtouris | delete a configuration option |
87 | 0c24b26b | Stavros Sachtouris | |
88 | 0c24b26b | Stavros Sachtouris | The above commands cause option values to be permanently stored in the Kamaki configuration file. |
89 | 0c24b26b | Stavros Sachtouris | |
90 | 0c24b26b | Stavros Sachtouris | Editing the configuration file |
91 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
92 | 0c24b26b | Stavros Sachtouris | |
93 | 329753ae | Stavros Sachtouris | The configuration file is a simple text file that can be created by the user. |
94 | 0c24b26b | Stavros Sachtouris | |
95 | 03d661d8 | Stavros Sachtouris | A simple way to create the configuration file is to set a configuration option using the kamaki config command. For example: |
96 | 03d661d8 | Stavros Sachtouris | |
97 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
98 | 0c24b26b | Stavros Sachtouris | |
99 | 7ae842c2 | Stavros Sachtouris | $ kamaki config set token myT0k3N== |
100 | 0c24b26b | Stavros Sachtouris | |
101 | 7ae842c2 | Stavros Sachtouris | In the above example, if the kamaki configuration file does not exist, it will be created with all the default values plus the *global.token* option set to *myT0k3n==* value. |
102 | 0c24b26b | Stavros Sachtouris | |
103 | 7536c9bf | Stavros Sachtouris | 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:: |
104 | 0c24b26b | Stavros Sachtouris | |
105 | 7536c9bf | Stavros Sachtouris | [store] |
106 | 7536c9bf | Stavros Sachtouris | url=https://okeanos.grnet.gr/pithos |
107 | 7ae842c2 | Stavros Sachtouris | token=my0th3rT0k3n== |
108 | 0c24b26b | Stavros Sachtouris | |
109 | 7ae842c2 | Stavros Sachtouris | two configuration options are created: *store.url* and *store.token*. These values will be loaded at every future kamaki execution. |
110 | 0c24b26b | Stavros Sachtouris | |
111 | 0c24b26b | Stavros Sachtouris | Available options |
112 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^ |
113 | 0c24b26b | Stavros Sachtouris | |
114 | 7ae842c2 | Stavros Sachtouris | 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 token, url, cli. In case of conflict, the most specific options overrides the global ones. |
115 | 0c24b26b | Stavros Sachtouris | |
116 | 0c24b26b | Stavros Sachtouris | * global.colors <on|off> |
117 | 7536c9bf | Stavros Sachtouris | enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored |
118 | 0c24b26b | Stavros Sachtouris | |
119 | 85e3803d | Stavros Sachtouris | * global.token <user authentication token> |
120 | 0c24b26b | Stavros Sachtouris | |
121 | 0c24b26b | Stavros Sachtouris | * store.cli <UI command specifications for store> |
122 | 0c24b26b | Stavros Sachtouris | 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. |
123 | 0c24b26b | Stavros Sachtouris | |
124 | 0c24b26b | Stavros Sachtouris | * store.url <OOS storage or Pithos+ service url> |
125 | 0c24b26b | Stavros Sachtouris | 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. |
126 | 0c24b26b | Stavros Sachtouris | |
127 | f5d9bc54 | Stavros Sachtouris | * store.token <token> |
128 | f5d9bc54 | Stavros Sachtouris | it set, it overrides possible global.token option for store level commands |
129 | f5d9bc54 | Stavros Sachtouris | |
130 | 0c24b26b | Stavros Sachtouris | * compute.url <OOS compute or Cyclades service url> |
131 | 0c24b26b | Stavros Sachtouris | 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. |
132 | 0c24b26b | Stavros Sachtouris | |
133 | 0c24b26b | Stavros Sachtouris | * cyclades.cli <UI command specifications for cyclades> |
134 | 0c24b26b | Stavros Sachtouris | a special package that is used to load cyclades commands to kamaki UIs. Don't touch this unless you know what you are doing. |
135 | 0c24b26b | Stavros Sachtouris | |
136 | 0c24b26b | Stavros Sachtouris | * flavor.cli <UI command specifications for VM flavors> |
137 | 0c24b26b | Stavros Sachtouris | 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. |
138 | 0c24b26b | Stavros Sachtouris | |
139 | 0c24b26b | Stavros Sachtouris | * network.cli <UI command specifications for virtual networks> |
140 | 0c24b26b | Stavros Sachtouris | 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. |
141 | 0c24b26b | Stavros Sachtouris | |
142 | d88ba587 | Stavros Sachtouris | * image.url <Plankton image service url> |
143 | d88ba587 | Stavros Sachtouris | 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. |
144 | 0c24b26b | Stavros Sachtouris | |
145 | d88ba587 | Stavros Sachtouris | * image.cli <UI command specifications for Plankton and Cyclades image service> |
146 | 0c24b26b | Stavros Sachtouris | 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. |
147 | 0c24b26b | Stavros Sachtouris | |
148 | 0c24b26b | Stavros Sachtouris | * astakos.url <Astakos authentication service url> |
149 | 0c24b26b | Stavros Sachtouris | 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. |
150 | 0c24b26b | Stavros Sachtouris | |
151 | 0c24b26b | Stavros Sachtouris | * astakos.cli <UI command specifications for Astakos authentication service> |
152 | 329753ae | Stavros Sachtouris | 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. |
153 | 329753ae | Stavros Sachtouris | |
154 | a6370d73 | Stavros Sachtouris | * history.file <history file path> |
155 | 7536c9bf | Stavros Sachtouris | 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 |
156 | a6370d73 | Stavros Sachtouris | |
157 | 329753ae | Stavros Sachtouris | Hidden features |
158 | 329753ae | Stavros Sachtouris | ^^^^^^^^^^^^^^^ |
159 | 329753ae | Stavros Sachtouris | |
160 | f5f2dc53 | Stavros Sachtouris | The livetest suite |
161 | f5f2dc53 | Stavros Sachtouris | """""""""""""""""" |
162 | 329753ae | Stavros Sachtouris | |
163 | f5f2dc53 | Stavros Sachtouris | Kamaki contains a live test suite for the kamaki.clients API, where "live" means that the tests are performed against active services that up and running. The live test package is named "livetest", it is accessible as kamaki.clients.livetest and it is designed to check the actual relation between kamaki and synnefo services. |
164 | 329753ae | Stavros Sachtouris | |
165 | f5f2dc53 | Stavros Sachtouris | The livetest suite can be activated with the following option on the configuration file:: |
166 | f5d9bc54 | Stavros Sachtouris | |
167 | f5f2dc53 | Stavros Sachtouris | [livetest] |
168 | f5f2dc53 | Stavros Sachtouris | cli=livetest_cli |
169 | f5f2dc53 | Stavros Sachtouris | |
170 | f5f2dc53 | Stavros Sachtouris | In most tests, livetest will run as long as an Astakos identity manager service is accessible and kamaki is set up to authenticate a valid token on this server. |
171 | f5f2dc53 | Stavros Sachtouris | |
172 | f5f2dc53 | Stavros Sachtouris | In specific, a setup file needs at least the following mandatory settings in the configuration file: |
173 | f5f2dc53 | Stavros Sachtouris | |
174 | f5f2dc53 | Stavros Sachtouris | * If authentication information is used for default kamaki clients:: |
175 | f5f2dc53 | Stavros Sachtouris | |
176 | f5f2dc53 | Stavros Sachtouris | [astakos] |
177 | f5f2dc53 | Stavros Sachtouris | url=<Astakos Identity Manager URL> |
178 | f5f2dc53 | Stavros Sachtouris | token=<A valid user token> |
179 | f5f2dc53 | Stavros Sachtouris | |
180 | f5f2dc53 | Stavros Sachtouris | * else if this authentication information is only for testing add this under [livetest]:: |
181 | f5f2dc53 | Stavros Sachtouris | |
182 | f5f2dc53 | Stavros Sachtouris | astakos_url=<Astakos Identity Manager URL> |
183 | f5f2dc53 | Stavros Sachtouris | astakos_token=<A valid user token> |
184 | f5f2dc53 | Stavros Sachtouris | |
185 | f5f2dc53 | Stavros Sachtouris | Each service tested in livetest might need some more options under the [livetest] label, as shown bellow: |
186 | f5f2dc53 | Stavros Sachtouris | |
187 | f5f2dc53 | Stavros Sachtouris | * kamaki livetest astakos:: |
188 | f5f2dc53 | Stavros Sachtouris | |
189 | f5f2dc53 | Stavros Sachtouris | astakos_email = <The valid email of testing user> |
190 | f5f2dc53 | Stavros Sachtouris | astakos_name = <The exact "real" name of testing user> |
191 | f5f2dc53 | Stavros Sachtouris | astakos_username = <The username of the testing user> |
192 | f5f2dc53 | Stavros Sachtouris | astakos_uuid = <The valid unique user id of the testing user> |
193 | f5f2dc53 | Stavros Sachtouris | |
194 | f5f2dc53 | Stavros Sachtouris | * kamaki livetest pithos:: |
195 | f5f2dc53 | Stavros Sachtouris | |
196 | f5f2dc53 | Stavros Sachtouris | astakos_uuid = <The valid unique user id of the testing user> |
197 | f5f2dc53 | Stavros Sachtouris | |
198 | f5f2dc53 | Stavros Sachtouris | * kamaki livetest cyclades / image:: |
199 | f5f2dc53 | Stavros Sachtouris | |
200 | f5f2dc53 | Stavros Sachtouris | image_id = <A valid image id used for testing> |
201 | f5f2dc53 | Stavros Sachtouris | image_local_path = <The local path of the testing image> |
202 | f5f2dc53 | Stavros Sachtouris | image_details = <A text file containing testing image details in a python dict> |
203 | f5f2dc53 | Stavros Sachtouris | |
204 | f5f2dc53 | Stavros Sachtouris | - example image.details content: |
205 | f5f2dc53 | Stavros Sachtouris | { |
206 | f5f2dc53 | Stavros Sachtouris | u'id': u'b3e68235-3abd-4d60-adfe-1379a4f8d3fe', |
207 | f5f2dc53 | Stavros Sachtouris | u'metadata': { |
208 | f5f2dc53 | Stavros Sachtouris | u'values': { |
209 | f5f2dc53 | Stavros Sachtouris | u'description': u'Debian 6.0.6 (Squeeze) Base System', |
210 | f5f2dc53 | Stavros Sachtouris | u'gui': u'No GUI', |
211 | f5f2dc53 | Stavros Sachtouris | u'kernel': u'2.6.32', |
212 | f5f2dc53 | Stavros Sachtouris | u'os': u'debian', |
213 | f5f2dc53 | Stavros Sachtouris | u'osfamily': u'linux', |
214 | f5f2dc53 | Stavros Sachtouris | u'root_partition': u'1', |
215 | f5f2dc53 | Stavros Sachtouris | u'sortorder': u'1', |
216 | f5f2dc53 | Stavros Sachtouris | u'users': u'root' |
217 | f5f2dc53 | Stavros Sachtouris | } |
218 | f5f2dc53 | Stavros Sachtouris | }, |
219 | f5f2dc53 | Stavros Sachtouris | u'name': u'Debian Base', |
220 | f5f2dc53 | Stavros Sachtouris | u'progress': u'100', |
221 | f5f2dc53 | Stavros Sachtouris | u'status': u'ACTIVE', |
222 | f5f2dc53 | Stavros Sachtouris | u'created': u'2012-11-19T14:54:57+00:00', |
223 | f5f2dc53 | Stavros Sachtouris | u'updated': u'2012-11-19T15:29:51+00:00' |
224 | f5f2dc53 | Stavros Sachtouris | } |
225 | f5f2dc53 | Stavros Sachtouris | |
226 | f5f2dc53 | Stavros Sachtouris | flavor_details = <A text file containing the testing images' flavor details in a python dict> |
227 | f5f2dc53 | Stavros Sachtouris | |
228 | f5f2dc53 | Stavros Sachtouris | - example flavor.details content: |
229 | f5f2dc53 | Stavros Sachtouris | { |
230 | f5f2dc53 | Stavros Sachtouris | u'name': u'C1R1drbd', |
231 | f5f2dc53 | Stavros Sachtouris | u'ram': 1024, |
232 | f5f2dc53 | Stavros Sachtouris | u'id': 1, |
233 | f5f2dc53 | Stavros Sachtouris | u'SNF:disk_template': u'drbd', |
234 | f5f2dc53 | Stavros Sachtouris | u'disk': 20, |
235 | f5f2dc53 | Stavros Sachtouris | u'cpu': 1 |
236 | f5f2dc53 | Stavros Sachtouris | } |
237 | f5f2dc53 | Stavros Sachtouris | |
238 | f5f2dc53 | Stavros Sachtouris | After setup, kamaki can run all tests:: |
239 | f5f2dc53 | Stavros Sachtouris | |
240 | f5f2dc53 | Stavros Sachtouris | $ kamaki livetest all |
241 | f5f2dc53 | Stavros Sachtouris | |
242 | f5f2dc53 | Stavros Sachtouris | a specific test (e.g. astakos):: |
243 | f5f2dc53 | Stavros Sachtouris | |
244 | f5f2dc53 | Stavros Sachtouris | $ kamaki livetest astakos |
245 | f5f2dc53 | Stavros Sachtouris | |
246 | f5f2dc53 | Stavros Sachtouris | or a specific method from a service (e.g. astakos authenticate):: |
247 | f5f2dc53 | Stavros Sachtouris | |
248 | f5f2dc53 | Stavros Sachtouris | $ kamaki livetest astakos authenticate |
249 | f5f2dc53 | Stavros Sachtouris | |
250 | f5f2dc53 | Stavros Sachtouris | The quotaholder client |
251 | f5f2dc53 | Stavros Sachtouris | """""""""""""""""""""" |
252 | f5f2dc53 | Stavros Sachtouris | |
253 | f5f2dc53 | Stavros Sachtouris | 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:: |
254 | f5d9bc54 | Stavros Sachtouris | |
255 | f5d9bc54 | Stavros Sachtouris | [quotaholder] |
256 | f5d9bc54 | Stavros Sachtouris | cli=quotaholder_cli |
257 | f5d9bc54 | Stavros Sachtouris | url=<URL of quotaholder service> |
258 | f5f2dc53 | Stavros Sachtouris | |
259 | f5f2dc53 | Stavros Sachtouris | Quotaholder is not tested in livetest |