root / docs / setup.rst @ 52b2b3bd
History | View | Annotate | Download (19.6 kB)
1 | 85e3803d | Stavros Sachtouris | Setup |
---|---|---|---|
2 | 85e3803d | Stavros Sachtouris | ===== |
3 | 0c24b26b | Stavros Sachtouris | |
4 | a4986073 | Stavros Sachtouris | Kamaki is easy to install from the official repository or with the pypi mechanism. |
5 | 0c24b26b | Stavros Sachtouris | |
6 | c52d1b08 | Stavros Sachtouris | Quick Setup |
7 | c52d1b08 | Stavros Sachtouris | ----------- |
8 | c52d1b08 | Stavros Sachtouris | |
9 | 2bd23362 | Stavros Sachtouris | .. warning:: Users of kamaki 0.8.X or older should consult the |
10 | 2bd23362 | Stavros Sachtouris | `migration guide <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_ first. |
11 | c52d1b08 | Stavros Sachtouris | |
12 | 16d7b9ff | Stavros Sachtouris | To set up Kamaki for a specific Synnefo deployment, users need an |
13 | 16d7b9ff | Stavros Sachtouris | **authentication URL** and a **user token**. Users should also pick an alias to |
14 | 16d7b9ff | Stavros Sachtouris | name the cloud configuration. This can be any single word, e.g., "default", |
15 | a4986073 | Stavros Sachtouris | "mycloud" or whatever suits the user. |
16 | fa479dc3 | Stavros Sachtouris | |
17 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
18 | abfaa6d9 | Vangelis Koukis | |
19 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.<cloud alias>.url <cloud-authentication-URL> |
20 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.<cloud alias>.token myt0k3n== |
21 | fa479dc3 | Stavros Sachtouris | |
22 | 16d7b9ff | Stavros Sachtouris | If only one cloud is configured, it is automatically considered the default. |
23 | fa382f9e | Stavros Sachtouris | Otherwise, a default cloud should be specified: |
24 | fa382f9e | Stavros Sachtouris | |
25 | fa382f9e | Stavros Sachtouris | .. code-block:: console |
26 | fa382f9e | Stavros Sachtouris | |
27 | fa382f9e | Stavros Sachtouris | $ kamaki config set default_cloud <cloud alias> |
28 | fa382f9e | Stavros Sachtouris | |
29 | a4986073 | Stavros Sachtouris | The endpoints (URLs) for each service are resolved automatically from a single |
30 | a4986073 | Stavros Sachtouris | URL. This mechanism works for Synnefo v0.14 deployments or later. The |
31 | a4986073 | Stavros Sachtouris | authentication URL is retrieved from the Synnefo Web UI and should be set as |
32 | a4986073 | Stavros Sachtouris | the cloud URL for kamaki. Users of Synnefo clouds >=0.14 are advised against |
33 | a4986073 | Stavros Sachtouris | using any service-specific URLs. |
34 | 904091dd | Stavros Sachtouris | |
35 | a4986073 | Stavros Sachtouris | Migrating configuration file to latest version |
36 | a4986073 | Stavros Sachtouris | ---------------------------------------------- |
37 | fa479dc3 | Stavros Sachtouris | |
38 | a4986073 | Stavros Sachtouris | Each new version of kamaki might demand some changes to the configuration file. |
39 | a4986073 | Stavros Sachtouris | Kamaki features a mechanism of automatic migration of the configration file to |
40 | a4986073 | Stavros Sachtouris | the latest version, which involves heuristics for guessing and translating the |
41 | a4986073 | Stavros Sachtouris | file. |
42 | a4986073 | Stavros Sachtouris | |
43 | a4986073 | Stavros Sachtouris | Quick migration |
44 | a4986073 | Stavros Sachtouris | ^^^^^^^^^^^^^^^ |
45 | a4986073 | Stavros Sachtouris | |
46 | a4986073 | Stavros Sachtouris | The easiest way is to backup and remove the configuration file. The default |
47 | a4986073 | Stavros Sachtouris | configuration file location is '${HOME}/.kamakirc'. |
48 | a4986073 | Stavros Sachtouris | |
49 | a4986073 | Stavros Sachtouris | To reset kamaki, a user needs the authentication URL and TOKEN: |
50 | fa479dc3 | Stavros Sachtouris | |
51 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
52 | fa479dc3 | Stavros Sachtouris | |
53 | a4986073 | Stavros Sachtouris | $ kamaki config set cloud.default.url URL |
54 | a4986073 | Stavros Sachtouris | $ kamaki config set cloud.default.token TOKEN |
55 | a4986073 | Stavros Sachtouris | |
56 | a4986073 | Stavros Sachtouris | After that, a new configuration file will be created. In most cases, this is |
57 | a4986073 | Stavros Sachtouris | enough, since kamaki automatically sets the correct options for every |
58 | a4986073 | Stavros Sachtouris | functionality. |
59 | a4986073 | Stavros Sachtouris | |
60 | a4986073 | Stavros Sachtouris | Automatic migration |
61 | a4986073 | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^ |
62 | a4986073 | Stavros Sachtouris | |
63 | a4986073 | Stavros Sachtouris | Another way is to let kamaki change the file automatically. Kamaki always |
64 | a4986073 | Stavros Sachtouris | inspects the configuration file and, if understood as an older version, it |
65 | a4986073 | Stavros Sachtouris | suggests some necessary modifications (user permission is required). |
66 | fa479dc3 | Stavros Sachtouris | |
67 | a4986073 | Stavros Sachtouris | On example 2.1 we suggest using the `user info` command to invoke the migration |
68 | a4986073 | Stavros Sachtouris | mechanism. |
69 | fa479dc3 | Stavros Sachtouris | |
70 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
71 | fa479dc3 | Stavros Sachtouris | :emphasize-lines: 1 |
72 | fa479dc3 | Stavros Sachtouris | |
73 | 904091dd | Stavros Sachtouris | Example 2.1: Convert config file while authenticating user "exampleuser" |
74 | fa479dc3 | Stavros Sachtouris | |
75 | a4986073 | Stavros Sachtouris | $ kamaki user info |
76 | a4986073 | Stavros Sachtouris | Config file format version >= 0.12 is required |
77 | fa382f9e | Stavros Sachtouris | Configuration file: "/home/exampleuser/.kamakirc" |
78 | fa479dc3 | Stavros Sachtouris | but kamaki can fix this: |
79 | fa479dc3 | Stavros Sachtouris | Calculating changes while preserving information |
80 | fa382f9e | Stavros Sachtouris | ... rescue global.token => cloud.default.token |
81 | fa479dc3 | Stavros Sachtouris | ... rescue config.cli => global.config_cli |
82 | fa479dc3 | Stavros Sachtouris | ... rescue history.file => global.history_file |
83 | a4986073 | Stavros Sachtouris | ... change global.network_cli value: `cyclades` => `network` |
84 | fa479dc3 | Stavros Sachtouris | ... DONE |
85 | fa479dc3 | Stavros Sachtouris | The following information will NOT be preserved: |
86 | abfaa6d9 | Vangelis Koukis | global.account = |
87 | fa479dc3 | Stavros Sachtouris | global.data_log = on |
88 | fa479dc3 | Stavros Sachtouris | user.account = exampleuser@example.com |
89 | fa479dc3 | Stavros Sachtouris | user.url = https://accounts.okeanos.grnet.gr |
90 | fa479dc3 | Stavros Sachtouris | compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1 |
91 | fa479dc3 | Stavros Sachtouris | file.url = https://pithos.okeanos.grnet.gr/v1 |
92 | fa479dc3 | Stavros Sachtouris | image.url = https://cyclades.okeanos.grnet.gr/plankton |
93 | fa479dc3 | Stavros Sachtouris | |
94 | a4986073 | Stavros Sachtouris | Kamaki is ready to convert the config file to version 0.12 |
95 | fa479dc3 | Stavros Sachtouris | Overwrite file /home/exampleuser/.kamakirc ? [Y, y] |
96 | fa479dc3 | Stavros Sachtouris | |
97 | fa479dc3 | Stavros Sachtouris | At this point, we should examine the kamaki output. Most options are renamed to |
98 | 2bd23362 | Stavros Sachtouris | match the latest configuration file version specifications. |
99 | fa479dc3 | Stavros Sachtouris | |
100 | 16d7b9ff | Stavros Sachtouris | Lets take a look at the discarded options: |
101 | fa479dc3 | Stavros Sachtouris | |
102 | a4986073 | Stavros Sachtouris | * `global.account` and `user.account` are not used since version 0.9 |
103 | 904091dd | Stavros Sachtouris | The same is true for the synonyms `store.account` and `pithos.account`. |
104 | 904091dd | Stavros Sachtouris | These options were used to explicitly set a user account or uuid to a |
105 | 904091dd | Stavros Sachtouris | pithos call. In the latest Synnefo version (>= 0.14), these features are |
106 | 904091dd | Stavros Sachtouris | meaningless and therefore omitted. |
107 | fa479dc3 | Stavros Sachtouris | |
108 | 904091dd | Stavros Sachtouris | * `global.data_log` option has never been a valid kamaki config option. |
109 | 2bd23362 | Stavros Sachtouris | In this scenario, the user wanted to set the `log_data` option, but he or |
110 | 2bd23362 | Stavros Sachtouris | she typed `data_log` instead. To fix this, the user should manually set the |
111 | 2bd23362 | Stavros Sachtouris | correct option after the conversion is complete (Example 2.2). |
112 | fa479dc3 | Stavros Sachtouris | |
113 | 2bd23362 | Stavros Sachtouris | Users should press *y* when they are ready, which will cause the default config |
114 | a4986073 | Stavros Sachtouris | file to be modified. |
115 | fa479dc3 | Stavros Sachtouris | |
116 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
117 | fa479dc3 | Stavros Sachtouris | :emphasize-lines: 1 |
118 | fa479dc3 | Stavros Sachtouris | |
119 | fa479dc3 | Stavros Sachtouris | Example 2.2: Rescue misspelled log_data option |
120 | fa479dc3 | Stavros Sachtouris | |
121 | fa479dc3 | Stavros Sachtouris | $ kamaki config set log_data on |
122 | fa479dc3 | Stavros Sachtouris | |
123 | 904091dd | Stavros Sachtouris | In order to convert more files, users may run kamaki with the -c option, which |
124 | 904091dd | Stavros Sachtouris | runs kamaki with a different configuration file (Example 2.3) and apply the |
125 | 904091dd | Stavros Sachtouris | steps described above. |
126 | d6737e18 | Stavros Sachtouris | |
127 | c52d1b08 | Stavros Sachtouris | .. code-block:: console |
128 | c52d1b08 | Stavros Sachtouris | :emphasize-lines: 1 |
129 | c52d1b08 | Stavros Sachtouris | |
130 | fa479dc3 | Stavros Sachtouris | Example 2.3: Use kamaki to update a configuration file called ".myfilerc" |
131 | c52d1b08 | Stavros Sachtouris | |
132 | fa479dc3 | Stavros Sachtouris | $ kamaki -c .myfilerc user authenticate |
133 | c52d1b08 | Stavros Sachtouris | |
134 | fa382f9e | Stavros Sachtouris | Multiple clouds |
135 | fa382f9e | Stavros Sachtouris | --------------- |
136 | 904091dd | Stavros Sachtouris | |
137 | 904091dd | Stavros Sachtouris | The following refers to users of multiple Synnefo and/or Open Stack |
138 | 16d7b9ff | Stavros Sachtouris | deployments. In the following, a Synnefo (or Open Stack) cloud deployment will |
139 | 2bd23362 | Stavros Sachtouris | be called **a cloud**. |
140 | 904091dd | Stavros Sachtouris | |
141 | 2bd23362 | Stavros Sachtouris | Multiple clouds can be configured and manager in a single kamaki setup, since |
142 | 2bd23362 | Stavros Sachtouris | version 0.9. Each cloud corresponds to a Synnefo (or Open Stack) cloud |
143 | 2bd23362 | Stavros Sachtouris | deployment, with each deployment offering a single point of authentication (an |
144 | 2bd23362 | Stavros Sachtouris | **authentication URL** and **token** pair). Users can retrieve this information |
145 | 2bd23362 | Stavros Sachtouris | through the cloud UI. |
146 | 904091dd | Stavros Sachtouris | |
147 | fa382f9e | Stavros Sachtouris | Once a user has retrieved one URL/token pair per cloud, it is time to assign a |
148 | 2bd23362 | Stavros Sachtouris | name to each cloud and configure kamaki accordingly. |
149 | 904091dd | Stavros Sachtouris | |
150 | fa382f9e | Stavros Sachtouris | For example, let the user have access to two clouds with the following authentication information :: |
151 | 904091dd | Stavros Sachtouris | |
152 | 904091dd | Stavros Sachtouris | cloud alias: devel |
153 | 904091dd | Stavros Sachtouris | authentication URL: https://devel.example.com/astakos/identity/v2.0/ |
154 | 904091dd | Stavros Sachtouris | authentication token: myd3v3170k3n== |
155 | 904091dd | Stavros Sachtouris | |
156 | 904091dd | Stavros Sachtouris | cloud alias: testing |
157 | 904091dd | Stavros Sachtouris | autentication URL: https://testing.example.com/astakos/identity/v2.0/ |
158 | 904091dd | Stavros Sachtouris | authentication token: my73571ng70k3n== |
159 | 904091dd | Stavros Sachtouris | |
160 | 904091dd | Stavros Sachtouris | .. note:: the cloud alias is arbitrary and decided by the user. It is just a |
161 | 2bd23362 | Stavros Sachtouris | reference label for the cloud setup in the kamaki context. |
162 | 904091dd | Stavros Sachtouris | |
163 | 904091dd | Stavros Sachtouris | The user should let kamaki know about these setups: |
164 | 904091dd | Stavros Sachtouris | |
165 | 904091dd | Stavros Sachtouris | .. code-block:: console |
166 | 904091dd | Stavros Sachtouris | |
167 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/ |
168 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.devel.token myd3v3170k3n== |
169 | 904091dd | Stavros Sachtouris | $ |
170 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/ |
171 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.testing.token my73571ng70k3n== |
172 | 904091dd | Stavros Sachtouris | $ |
173 | 904091dd | Stavros Sachtouris | |
174 | fa382f9e | Stavros Sachtouris | To check if all settings are loaded, a user may list all clouds, as shown |
175 | 904091dd | Stavros Sachtouris | bellow: |
176 | 904091dd | Stavros Sachtouris | |
177 | 904091dd | Stavros Sachtouris | .. code-block:: console |
178 | 904091dd | Stavros Sachtouris | |
179 | 2bd23362 | Stavros Sachtouris | $ kamaki config get cloud |
180 | fa382f9e | Stavros Sachtouris | cloud.default.url = https://example.com/astakos.identity/v2.0/ |
181 | 2bd23362 | Stavros Sachtouris | cloud.default.token = myd3f4u1770k3n== |
182 | fa382f9e | Stavros Sachtouris | cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/ |
183 | fa382f9e | Stavros Sachtouris | cloud.devel.token = myd3v3170k3n== |
184 | fa382f9e | Stavros Sachtouris | cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/ |
185 | fa382f9e | Stavros Sachtouris | cloud.testing.token = my73571ng70k3n== |
186 | 904091dd | Stavros Sachtouris | $ |
187 | 904091dd | Stavros Sachtouris | |
188 | fa382f9e | Stavros Sachtouris | or query kamaki for a specific cloud: |
189 | 904091dd | Stavros Sachtouris | |
190 | 904091dd | Stavros Sachtouris | .. code-block:: console |
191 | 904091dd | Stavros Sachtouris | |
192 | fa382f9e | Stavros Sachtouris | $ kamaki config get cloud.devel |
193 | fa382f9e | Stavros Sachtouris | cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/ |
194 | fa382f9e | Stavros Sachtouris | cloud.devel.token = myd3v3170k3n== |
195 | 904091dd | Stavros Sachtouris | $ |
196 | 904091dd | Stavros Sachtouris | |
197 | fa382f9e | Stavros Sachtouris | Now kamaki can use any of these clouds, with the **- - cloud** attribute. If |
198 | a4986073 | Stavros Sachtouris | the **- - cloud** option is omitted, kamaki will query the `default` cloud. |
199 | 904091dd | Stavros Sachtouris | |
200 | a4986073 | Stavros Sachtouris | One way to test this, is the `user info` command: |
201 | 904091dd | Stavros Sachtouris | |
202 | 904091dd | Stavros Sachtouris | .. code-block:: console |
203 | 904091dd | Stavros Sachtouris | |
204 | a4986073 | Stavros Sachtouris | $ kamaki --cloud=devel user info |
205 | 904091dd | Stavros Sachtouris | ... |
206 | a4986073 | Stavros Sachtouris | id : 725d5de4-1bab-45ac-9e98-38a60a8c543c |
207 | a4986073 | Stavros Sachtouris | name : Devel User |
208 | 904091dd | Stavros Sachtouris | $ |
209 | a4986073 | Stavros Sachtouris | $ kamaki --cloud=testing user info |
210 | 904091dd | Stavros Sachtouris | ... |
211 | a4986073 | Stavros Sachtouris | id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83 |
212 | a4986073 | Stavros Sachtouris | name : Testing User |
213 | 904091dd | Stavros Sachtouris | $ |
214 | a4986073 | Stavros Sachtouris | $ kamaki --cloud=default user info |
215 | 904091dd | Stavros Sachtouris | ... |
216 | a4986073 | Stavros Sachtouris | id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
217 | a4986073 | Stavros Sachtouris | name : Default User |
218 | 904091dd | Stavros Sachtouris | $ |
219 | a4986073 | Stavros Sachtouris | $ kamaki user info |
220 | 904091dd | Stavros Sachtouris | ... |
221 | a4986073 | Stavros Sachtouris | id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
222 | a4986073 | Stavros Sachtouris | name : Default User |
223 | 904091dd | Stavros Sachtouris | $ |
224 | 904091dd | Stavros Sachtouris | |
225 | a4986073 | Stavros Sachtouris | In interactive cell, the cloud option should be passed when calling the shell. |
226 | 904091dd | Stavros Sachtouris | |
227 | 2bd23362 | Stavros Sachtouris | .. code-block:: console |
228 | 2bd23362 | Stavros Sachtouris | |
229 | a4986073 | Stavros Sachtouris | $ kamaki-shell --cloud=devel |
230 | 2bd23362 | Stavros Sachtouris | kamaki v0.10 - Interactive Shell |
231 | 2bd23362 | Stavros Sachtouris | |
232 | 2bd23362 | Stavros Sachtouris | /exit terminate kamaki |
233 | 2bd23362 | Stavros Sachtouris | exit or ^D exit context |
234 | 2bd23362 | Stavros Sachtouris | ? or help available commands |
235 | 2bd23362 | Stavros Sachtouris | ?command help on command |
236 | 2bd23362 | Stavros Sachtouris | !<command> execute OS shell command |
237 | 2bd23362 | Stavros Sachtouris | |
238 | 2bd23362 | Stavros Sachtouris | Session user is Devel User |
239 | 2bd23362 | Stavros Sachtouris | (uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c) |
240 | 2bd23362 | Stavros Sachtouris | [kamaki]: |
241 | 2bd23362 | Stavros Sachtouris | |
242 | 2bd23362 | Stavros Sachtouris | |
243 | 0c24b26b | Stavros Sachtouris | Optional features |
244 | 0c24b26b | Stavros Sachtouris | ----------------- |
245 | 0c24b26b | Stavros Sachtouris | |
246 | fa479dc3 | Stavros Sachtouris | For installing any or all of the following, consult the |
247 | fa479dc3 | Stavros Sachtouris | `kamaki installation guide <installation.html#install-ansicolors>`_ |
248 | 961e6040 | Stavros Sachtouris | |
249 | 0c24b26b | Stavros Sachtouris | * ansicolors |
250 | fa382f9e | Stavros Sachtouris | * Add colors to command line / console output |
251 | fa382f9e | Stavros Sachtouris | * Can be switched on/off in kamaki configuration file: `colors = on/off` |
252 | 4054c46d | Stavros Sachtouris | * Has not been tested on non unix / linux based platforms |
253 | 0c24b26b | Stavros Sachtouris | |
254 | abfaa6d9 | Vangelis Koukis | * mock |
255 | 4054c46d | Stavros Sachtouris | * For kamaki contributors only |
256 | fa382f9e | Stavros Sachtouris | * Allow unit tests to run on kamaki.clients package |
257 | 4054c46d | Stavros Sachtouris | * Needs mock version 1.X or better |
258 | 0c24b26b | Stavros Sachtouris | |
259 | fa382f9e | Stavros Sachtouris | Any of the above features can be installed at any time before or after kamaki |
260 | fa382f9e | Stavros Sachtouris | installation. |
261 | 0c24b26b | Stavros Sachtouris | |
262 | 0c24b26b | Stavros Sachtouris | Configuration options |
263 | 0c24b26b | Stavros Sachtouris | --------------------- |
264 | 0c24b26b | Stavros Sachtouris | |
265 | 904091dd | Stavros Sachtouris | There are two kinds of configuration options: |
266 | 0c24b26b | Stavros Sachtouris | |
267 | 904091dd | Stavros Sachtouris | * kamaki-related (global) |
268 | abfaa6d9 | Vangelis Koukis | interface settings and constants of the kamaki internal mechanism, e.g., |
269 | 2bd23362 | Stavros Sachtouris | terminal colors, maximum threads per connection, custom logging, history |
270 | 2bd23362 | Stavros Sachtouris | file path, etc. |
271 | 0c24b26b | Stavros Sachtouris | |
272 | fa382f9e | Stavros Sachtouris | * cloud-related |
273 | fa382f9e | Stavros Sachtouris | information needed to connect and use one or more clouds. There are some |
274 | abfaa6d9 | Vangelis Koukis | mandatory options (URL, token) and some advanced / optional (e.g., |
275 | fa382f9e | Stavros Sachtouris | service-specific URL overrides or versions) |
276 | 0c24b26b | Stavros Sachtouris | |
277 | a4986073 | Stavros Sachtouris | Kamaki comes with preset default values to all kamaki-related configuration |
278 | 904091dd | Stavros Sachtouris | options. Cloud-related information is not included in presets and should be |
279 | fa382f9e | Stavros Sachtouris | provided by the user. Kamaki-related options can also be modified. |
280 | 0c24b26b | Stavros Sachtouris | |
281 | 904091dd | Stavros Sachtouris | There are two ways of managing configuration options: edit the config file or |
282 | 904091dd | Stavros Sachtouris | use the kamaki config command. |
283 | 904091dd | Stavros Sachtouris | |
284 | 904091dd | Stavros Sachtouris | Using multiple configuration files |
285 | 904091dd | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
286 | 904091dd | Stavros Sachtouris | |
287 | 904091dd | Stavros Sachtouris | Kamaki setups are stored in configuration files. By default, a Kamaki |
288 | 904091dd | Stavros Sachtouris | installation stores options in *.kamakirc* file located at the user home |
289 | 904091dd | Stavros Sachtouris | directory. |
290 | 904091dd | Stavros Sachtouris | |
291 | 904091dd | Stavros Sachtouris | If a user needs to switch between different kamaki-related setups, Kamaki can |
292 | fa382f9e | Stavros Sachtouris | explicitly load configuration files with the **- - config** (or **- c**) option |
293 | 0c24b26b | Stavros Sachtouris | |
294 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
295 | 03d661d8 | Stavros Sachtouris | |
296 | 03d661d8 | Stavros Sachtouris | $ kamaki --config <custom_config_file_path> [other options] |
297 | 0c24b26b | Stavros Sachtouris | |
298 | fa382f9e | Stavros Sachtouris | .. note:: For accessing multiple clouds, users do NOT need to create multiple |
299 | fa382f9e | Stavros Sachtouris | configuration files. Instead, we suggest using a single configuration file |
300 | fa382f9e | Stavros Sachtouris | with multiple cloud setups. More details can be found at the |
301 | fa382f9e | Stavros Sachtouris | `multiple clouds guide <#multiple-clouds>`_. |
302 | 0c24b26b | Stavros Sachtouris | |
303 | 0c24b26b | Stavros Sachtouris | Modifying options at runtime |
304 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
305 | 0c24b26b | Stavros Sachtouris | |
306 | 2bd23362 | Stavros Sachtouris | All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example: |
307 | 0c24b26b | Stavros Sachtouris | |
308 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
309 | 03d661d8 | Stavros Sachtouris | |
310 | 904091dd | Stavros Sachtouris | $ kamaki file list -o global.pithos_container=anothercontainer |
311 | 0c24b26b | Stavros Sachtouris | |
312 | 904091dd | Stavros Sachtouris | will invoke *kamaki file list* with the specified options, but the initial |
313 | 904091dd | Stavros Sachtouris | global.pithos_container values will not be modified. |
314 | 7ae842c2 | Stavros Sachtouris | |
315 | 2bd23362 | Stavros Sachtouris | |
316 | 0c24b26b | Stavros Sachtouris | Editing options |
317 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^ |
318 | 0c24b26b | Stavros Sachtouris | |
319 | 0c24b26b | Stavros Sachtouris | Kamaki config command allows users to see and manage all configuration options. |
320 | 0c24b26b | Stavros Sachtouris | |
321 | 0c24b26b | Stavros Sachtouris | * kamaki config list |
322 | a4986073 | Stavros Sachtouris | lists all configuration options |
323 | 0c24b26b | Stavros Sachtouris | |
324 | a4986073 | Stavros Sachtouris | * kamaki config get <group>[.option] | <option> |
325 | a4986073 | Stavros Sachtouris | show the value of a configuration option.A single *option* is equivalent to |
326 | a4986073 | Stavros Sachtouris | *global.option*, except if this group exist (*global*, *cloud*) |
327 | 0c24b26b | Stavros Sachtouris | |
328 | 0c24b26b | Stavros Sachtouris | * kamaki config set <group.option> <value> |
329 | 2bd23362 | Stavros Sachtouris | set the group.option to value. If no group is given, it defaults to |
330 | fa382f9e | Stavros Sachtouris | *global*. |
331 | 0c24b26b | Stavros Sachtouris | |
332 | a4986073 | Stavros Sachtouris | * kamaki config delete <group>[.option] | <option> |
333 | a4986073 | Stavros Sachtouris | delete a configuration option, group, or global option. |
334 | 0c24b26b | Stavros Sachtouris | |
335 | 0c24b26b | Stavros Sachtouris | The above commands cause option values to be permanently stored in the Kamaki configuration file. |
336 | 0c24b26b | Stavros Sachtouris | |
337 | fa382f9e | Stavros Sachtouris | The commands above can also be used for **clouds** handling, using the `cloud.` |
338 | fa382f9e | Stavros Sachtouris | prefix. The cloud handling cases are similar but with slightly different |
339 | fa382f9e | Stavros Sachtouris | semantics: |
340 | fa382f9e | Stavros Sachtouris | |
341 | fa382f9e | Stavros Sachtouris | * kamaki config get cloud[.<cloud alias>[.option]] |
342 | abfaa6d9 | Vangelis Koukis | * cloud |
343 | fa382f9e | Stavros Sachtouris | list all clouds and their settings |
344 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias> |
345 | fa382f9e | Stavros Sachtouris | list settings of the cloud aliased as <cloud alias>. If no |
346 | fa382f9e | Stavros Sachtouris | special is configured, use the term `cloud.default` |
347 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias>.<option> |
348 | 904091dd | Stavros Sachtouris | show the value of the specified option. If no special alias is |
349 | fa382f9e | Stavros Sachtouris | configured, use `cloud.default.<option>` |
350 | 904091dd | Stavros Sachtouris | |
351 | fa382f9e | Stavros Sachtouris | * kamaki config set cloud.<cloud alias>.<option> <value> |
352 | fa382f9e | Stavros Sachtouris | If the cloud alias <cloud alias> does not exist, create it. Then, create |
353 | fa382f9e | Stavros Sachtouris | (or update) the option <option> of this cloud, by setting its value |
354 | 904091dd | Stavros Sachtouris | to <value>. |
355 | 904091dd | Stavros Sachtouris | |
356 | fa382f9e | Stavros Sachtouris | * kamaki config delete cloud.<cloud alias>[.<option>] |
357 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias> |
358 | 904091dd | Stavros Sachtouris | delete the cloud alias <cloud alias> and all its options |
359 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias>.<option> |
360 | fa382f9e | Stavros Sachtouris | delete the <option> and its value from the cloud cloud aliased as |
361 | 904091dd | Stavros Sachtouris | <cloud alias> |
362 | 904091dd | Stavros Sachtouris | |
363 | 2bd23362 | Stavros Sachtouris | To see if a default cloud is configured, get the default_cloud value |
364 | fa382f9e | Stavros Sachtouris | |
365 | fa382f9e | Stavros Sachtouris | .. code-block:: console |
366 | fa382f9e | Stavros Sachtouris | |
367 | fa382f9e | Stavros Sachtouris | $ kamaki config get default_cloud |
368 | fa382f9e | Stavros Sachtouris | |
369 | 2bd23362 | Stavros Sachtouris | If no default_cloud value is set, the first cloud alias is picked as default. |
370 | 2bd23362 | Stavros Sachtouris | To pick a cloud alias as default: |
371 | 2bd23362 | Stavros Sachtouris | |
372 | 2bd23362 | Stavros Sachtouris | .. code-block:: console |
373 | 2bd23362 | Stavros Sachtouris | |
374 | 2bd23362 | Stavros Sachtouris | $ kamaki config set default_cloud <cloud alias> |
375 | 2bd23362 | Stavros Sachtouris | |
376 | 2bd23362 | Stavros Sachtouris | |
377 | 0c24b26b | Stavros Sachtouris | Editing the configuration file |
378 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
379 | 0c24b26b | Stavros Sachtouris | |
380 | 329753ae | Stavros Sachtouris | The configuration file is a simple text file that can be created by the user. |
381 | 0c24b26b | Stavros Sachtouris | |
382 | 2bd23362 | Stavros Sachtouris | .. note:: users of kamaki < 0.9 can use the latest versions to automatically |
383 | a4986073 | Stavros Sachtouris | convert their old configuration files to the new configuration file(s). See |
384 | a4986073 | Stavros Sachtouris | `these instructions <#mMigrating-configuration-file-to-latest-version>`_ |
385 | 2bd23362 | Stavros Sachtouris | for more. |
386 | abfaa6d9 | Vangelis Koukis | |
387 | 904091dd | Stavros Sachtouris | A simple way to create the configuration file is to set a configuration option |
388 | 904091dd | Stavros Sachtouris | using the kamaki config command. For example: |
389 | 03d661d8 | Stavros Sachtouris | |
390 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
391 | 0c24b26b | Stavros Sachtouris | |
392 | a4986073 | Stavros Sachtouris | $ kamaki config set log_file /home/exampleuser/logs/kamaki.log |
393 | 0c24b26b | Stavros Sachtouris | |
394 | 904091dd | Stavros Sachtouris | In the above example, if the kamaki configuration file does not exist, it will |
395 | 904091dd | Stavros Sachtouris | be created with all the default values plus the *global.log_file* option set to |
396 | 904091dd | Stavros Sachtouris | `/home/exampleuser/logs/kamaki.log` |
397 | 0c24b26b | Stavros Sachtouris | |
398 | 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:: |
399 | 0c24b26b | Stavros Sachtouris | |
400 | 904091dd | Stavros Sachtouris | [global] |
401 | 904091dd | Stavros Sachtouris | log_file = /home/exampleuser/logs/kamaki.log |
402 | 904091dd | Stavros Sachtouris | max_threads = 7 |
403 | 904091dd | Stavros Sachtouris | colors = off |
404 | 904091dd | Stavros Sachtouris | |
405 | fa382f9e | Stavros Sachtouris | [cloud "default"] |
406 | 904091dd | Stavros Sachtouris | url = |
407 | 904091dd | Stavros Sachtouris | token = |
408 | 904091dd | Stavros Sachtouris | |
409 | 2bd23362 | Stavros Sachtouris | In this scenario, a bunch of configuration options are created and set to their |
410 | 2bd23362 | Stavros Sachtouris | default options, except the log_file option which is set to whatever the |
411 | 2bd23362 | Stavros Sachtouris | specified value. |
412 | 904091dd | Stavros Sachtouris | |
413 | 2bd23362 | Stavros Sachtouris | The *[cloud "default"]* section is special and is used to configure the default |
414 | 2bd23362 | Stavros Sachtouris | cloud. Kamaki will not be able to do anything useful without proper url and |
415 | 2bd23362 | Stavros Sachtouris | token values set in the cloud section. |
416 | 0c24b26b | Stavros Sachtouris | |
417 | 0c24b26b | Stavros Sachtouris | Available options |
418 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^ |
419 | 0c24b26b | Stavros Sachtouris | |
420 | 2bd23362 | Stavros Sachtouris | The [*global*] group is treated by kamaki as a generic group for kamaki |
421 | 904091dd | Stavros Sachtouris | settings, namely command cli specifications, the thread limit, console colors, |
422 | 904091dd | Stavros Sachtouris | history and log files, log detail options and pithos-specific options. |
423 | 0c24b26b | Stavros Sachtouris | |
424 | 0ee7c2c2 | Stavros Sachtouris | * global.default_cloud <cloud name> |
425 | 0ee7c2c2 | Stavros Sachtouris | pick a cloud configuration as default. It must refer to an existing cloud. |
426 | 0ee7c2c2 | Stavros Sachtouris | |
427 | 0c24b26b | Stavros Sachtouris | * global.colors <on|off> |
428 | 0ee7c2c2 | Stavros Sachtouris | enable / disable colors in command line based uis. Requires ansicolors, |
429 | 0ee7c2c2 | Stavros Sachtouris | otherwise it is ignored |
430 | 0c24b26b | Stavros Sachtouris | |
431 | 31a30991 | Stavros Sachtouris | * global.log_file <logfile full path> |
432 | 9e87e4bb | Stavros Sachtouris | set a custom location for kamaki logging. Default value is ~/.kamaki.log |
433 | 31a30991 | Stavros Sachtouris | |
434 | 31a30991 | Stavros Sachtouris | * global.log_token <on|off> |
435 | 31a30991 | Stavros Sachtouris | allow kamaki to log user tokens |
436 | 31a30991 | Stavros Sachtouris | |
437 | 31a30991 | Stavros Sachtouris | * global.log_data <on|off> |
438 | 904091dd | Stavros Sachtouris | allow kamaki to log http data (by default, it logs only method, URL and |
439 | 904091dd | Stavros Sachtouris | headers) |
440 | 0c24b26b | Stavros Sachtouris | |
441 | 2bd23362 | Stavros Sachtouris | * global.log_pid <on|off> |
442 | 2bd23362 | Stavros Sachtouris | attach the process name and id that produces each log line. Useful for |
443 | 2bd23362 | Stavros Sachtouris | resolving race condition problems. |
444 | 2bd23362 | Stavros Sachtouris | |
445 | 904091dd | Stavros Sachtouris | * global.file_cli <UI command specifications for file> |
446 | 904091dd | Stavros Sachtouris | a special package that is used to load storage commands to kamaki UIs. |
447 | 904091dd | Stavros Sachtouris | Don't touch this unless if you know what you are doing. |
448 | 0c24b26b | Stavros Sachtouris | |
449 | 904091dd | Stavros Sachtouris | * global.cyclades_cli <UI command specifications for cyclades> |
450 | 904091dd | Stavros Sachtouris | a special package that is used to load cyclades commands to kamaki UIs. |
451 | 904091dd | Stavros Sachtouris | Don't touch this unless you know what you are doing. |
452 | f5d9bc54 | Stavros Sachtouris | |
453 | 904091dd | Stavros Sachtouris | * global.flavor_cli <UI command specifications for VM flavors> |
454 | 904091dd | Stavros Sachtouris | a special package that is used to load cyclades VM flavor commands to |
455 | 904091dd | Stavros Sachtouris | kamaki UIs. Don't touch this unless you know what you are doing. |
456 | 0c24b26b | Stavros Sachtouris | |
457 | 904091dd | Stavros Sachtouris | * global.network_cli <UI command specifications for virtual networks> |
458 | 0ee7c2c2 | Stavros Sachtouris | a special package that is used to load cyclades virtual network commands. |
459 | 0ee7c2c2 | Stavros Sachtouris | Don't touch this unless you know what you are doing. |
460 | 0ee7c2c2 | Stavros Sachtouris | |
461 | 0ee7c2c2 | Stavros Sachtouris | * global.ip_cli <UI command specifications for floating IPs> |
462 | 0ee7c2c2 | Stavros Sachtouris | a special package that is used to load cyclades floating IP commands. Don't |
463 | 0ee7c2c2 | Stavros Sachtouris | touch this unless you know what you are doing. |
464 | 0c24b26b | Stavros Sachtouris | |
465 | 904091dd | Stavros Sachtouris | * global.image_cli <UI command specs for Plankton or Compute image service> |
466 | 0ee7c2c2 | Stavros Sachtouris | a special package that is used to load image-related commands to kamaki UIs. |
467 | 0ee7c2c2 | Stavros Sachtouris | Don't touch this unless you know what you are doing. |
468 | 0c24b26b | Stavros Sachtouris | |
469 | 904091dd | Stavros Sachtouris | * global.user_cli <UI command specs for Astakos authentication service> |
470 | 904091dd | Stavros Sachtouris | a special package that is used to load astakos-related commands to kamaki |
471 | 904091dd | Stavros Sachtouris | UIs. Don't touch this unless you know what you are doing. |
472 | 329753ae | Stavros Sachtouris | |
473 | 904091dd | Stavros Sachtouris | * global.history_file <history file path> |
474 | 904091dd | Stavros Sachtouris | the path of a simple file for inter-session kamaki history. Make sure |
475 | 904091dd | Stavros Sachtouris | kamaki is executed in a context where this file is accessible for reading |
476 | 904091dd | Stavros Sachtouris | and writing. Kamaki automatically creates the file if it doesn't exist |
477 | a6370d73 | Stavros Sachtouris | |
478 | c5b9380c | Stavros Sachtouris | Additional features |
479 | c5b9380c | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^ |
480 | c5b9380c | Stavros Sachtouris | |
481 | 2bd23362 | Stavros Sachtouris | Functional tests |
482 | 2bd23362 | Stavros Sachtouris | """""""""""""""" |
483 | 329753ae | Stavros Sachtouris | |
484 | 2bd23362 | Stavros Sachtouris | Kamaki contains a set of functional tests for *kamaki.clients*, called |
485 | 2bd23362 | Stavros Sachtouris | "livetest". The term "live" means that the tests are performed against an |
486 | 2bd23362 | Stavros Sachtouris | on-line functional cloud deployment. The package is accessible as |
487 | 2bd23362 | Stavros Sachtouris | *kamaki.clients.livetest* . |
488 | 329753ae | Stavros Sachtouris | |
489 | 2bd23362 | Stavros Sachtouris | The livetest commands can be activated by setting the following option in the |
490 | 2bd23362 | Stavros Sachtouris | configuration file:: |
491 | f5d9bc54 | Stavros Sachtouris | |
492 | 904091dd | Stavros Sachtouris | [global] |
493 | 904091dd | Stavros Sachtouris | livetest_cli=livetest |
494 | 904091dd | Stavros Sachtouris | |
495 | 904091dd | Stavros Sachtouris | or with this kamaki command:: |
496 | f5f2dc53 | Stavros Sachtouris | |
497 | 2bd23362 | Stavros Sachtouris | $ kamaki config set livetest_cli livetest |
498 | f5f2dc53 | Stavros Sachtouris | |
499 | 2bd23362 | Stavros Sachtouris | In most cases, it is enough to have the default cloud configured correctly. |
500 | 2bd23362 | Stavros Sachtouris | Some commands, though, require some extra settings specific to actual contents |
501 | 2bd23362 | Stavros Sachtouris | of the cloud or the example files used in kamaki. |
502 | f5f2dc53 | Stavros Sachtouris | |
503 | 904091dd | Stavros Sachtouris | Here is a list of settings needed: |
504 | f5f2dc53 | Stavros Sachtouris | |
505 | 904091dd | Stavros Sachtouris | * for all tests:: |
506 | fa382f9e | Stavros Sachtouris | * livetest.testcloud = <the cloud alias this test will run against> |
507 | f5f2dc53 | Stavros Sachtouris | |
508 | 904091dd | Stavros Sachtouris | * for astakos client:: |
509 | 904091dd | Stavros Sachtouris | * livetest.astakos_details = <A file with an authentication output> |
510 | 904091dd | Stavros Sachtouris | To create this file, pipeline the output of an authentication command |
511 | 2bd23362 | Stavros Sachtouris | with the -j option for raw json output |
512 | f5f2dc53 | Stavros Sachtouris | |
513 | 904091dd | Stavros Sachtouris | .. code-block:: console |
514 | f5f2dc53 | Stavros Sachtouris | |
515 | 904091dd | Stavros Sachtouris | $ kamaki user authenticate -j > astakos.details |
516 | f5f2dc53 | Stavros Sachtouris | |
517 | 2bd23362 | Stavros Sachtouris | * livetest.astakos_name = <The exact "real" name of the testing user> |
518 | 904091dd | Stavros Sachtouris | * livetest.astakos_id = <The valid unique user id of the testing user> |
519 | f5f2dc53 | Stavros Sachtouris | |
520 | 904091dd | Stavros Sachtouris | * for image client: |
521 | 2bd23362 | Stavros Sachtouris | * livetest.image_details = <A file with the image metadata> |
522 | 904091dd | Stavros Sachtouris | To create this file, pipeline the output of an image metadata command |
523 | 2bd23362 | Stavros Sachtouris | with the -j option for raw json output |
524 | f5f2dc53 | Stavros Sachtouris | |
525 | 904091dd | Stavros Sachtouris | .. code-block:: console |
526 | f5f2dc53 | Stavros Sachtouris | |
527 | 82cc4b8f | Stavros Sachtouris | $ kamaki image info <img id> -j > img.details |
528 | f5f2dc53 | Stavros Sachtouris | |
529 | 904091dd | Stavros Sachtouris | * livetest.image_id = <A valid image id used for testing> |
530 | 904091dd | Stavros Sachtouris | * livetest.image_local_path = <The local path of the testing image> |
531 | f5f2dc53 | Stavros Sachtouris | |
532 | 904091dd | Stavros Sachtouris | * for flavors (part of the compute client): |
533 | 904091dd | Stavros Sachtouris | * livetest.flavor_details = <A file with the flavor details> |
534 | 904091dd | Stavros Sachtouris | To create this file, pipeline the output of a flavor info command |
535 | 2bd23362 | Stavros Sachtouris | with the -j option for raw json output |
536 | f5f2dc53 | Stavros Sachtouris | |
537 | 904091dd | Stavros Sachtouris | .. code-block:: console |
538 | f5f2dc53 | Stavros Sachtouris | |
539 | 904091dd | Stavros Sachtouris | $ kamaki flavor info <flavor id> -j > flavor.details |
540 | f5f2dc53 | Stavros Sachtouris | |
541 | f5f2dc53 | Stavros Sachtouris | |
542 | f5f2dc53 | Stavros Sachtouris | After setup, kamaki can run all tests:: |
543 | f5f2dc53 | Stavros Sachtouris | |
544 | f5f2dc53 | Stavros Sachtouris | $ kamaki livetest all |
545 | f5f2dc53 | Stavros Sachtouris | |
546 | 2bd23362 | Stavros Sachtouris | a specific test (e.g., pithos scenario):: |
547 | 2bd23362 | Stavros Sachtouris | |
548 | 2bd23362 | Stavros Sachtouris | $ kamaki livetest pithos |
549 | f5f2dc53 | Stavros Sachtouris | |
550 | 2bd23362 | Stavros Sachtouris | or a specific method from a service (e.g., create_server @ cyclades):: |
551 | f5f2dc53 | Stavros Sachtouris | |
552 | 2bd23362 | Stavros Sachtouris | $ kamaki livetest cyclades create_server |
553 | f5f2dc53 | Stavros Sachtouris | |
554 | f5f2dc53 | Stavros Sachtouris | |
555 | 76769d2f | Stavros Sachtouris | Unit tests |
556 | 76769d2f | Stavros Sachtouris | """""""""" |
557 | 4054c46d | Stavros Sachtouris | |
558 | a4986073 | Stavros Sachtouris | Kamaki features a set of unit tests for the kamaki.clients package. This set is |
559 | a4986073 | Stavros Sachtouris | not used when kamaki is running. Instead, it is aimed to developers who debug |
560 | a4986073 | Stavros Sachtouris | or extent kamaki. For more information, check the |
561 | 904091dd | Stavros Sachtouris | `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the |
562 | 904091dd | Stavros Sachtouris | `developers section <developers/extending-clients-api.html>`_. |