root / docs / collection_of_examples / examples.rst @ b4ed3a7e
History | View | Annotate | Download (12.3 kB)
1 |
Examples |
---|---|
2 |
======== |
3 |
|
4 |
This section contains a collection of the most common operations with kamaki. |
5 |
|
6 |
.. note:: all examples bellow use `bash` in a linux enviroment, but they can be |
7 |
replicated in a reasonable command line shell in any popular platform. |
8 |
|
9 |
Configuration |
10 |
------------- |
11 |
|
12 |
Since kamaki 0.9, the format of the configuration file has changed. In this |
13 |
scenario, we have an old configuration file at ${HOME}/.kamakirc that we need |
14 |
to convert. We also create a new one from scratch. In both cases, we have to |
15 |
set up one or more clouds in a single configuration and we also examine a case |
16 |
of multiple configurations. |
17 |
|
18 |
Convert old configuration file |
19 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
20 |
|
21 |
First, back up the old file |
22 |
|
23 |
.. code-block:: console |
24 |
|
25 |
$ cp ~/.kamakirc ~/backups/.kamakirc |
26 |
|
27 |
Now, let kamaki do the conversion |
28 |
|
29 |
.. code-block:: console |
30 |
|
31 |
$ kamaki user authenticate |
32 |
. Config file format version >= 9.0 is required |
33 |
. Configuration file: /home/someuser/.kamakirc |
34 |
. Attempting to fix this: |
35 |
. Calculating changes while preserving information |
36 |
. ... rescue global.token => cloud.default.token |
37 |
. ... rescue user.cli => global.user_cli |
38 |
. ... rescue network.cli => global.network_cli |
39 |
. ... rescue file.cli => global.file_cli |
40 |
. ... rescue flavor.cli => global.flavor_cli |
41 |
. ... rescue config.cli => global.config_cli |
42 |
. ... rescue image.cli => global.image_cli |
43 |
. ... rescue server.cli => global.server_cli |
44 |
. ... rescue history.file => global.history_file |
45 |
. ... rescue history.cli => global.history_cli |
46 |
. ... DONE |
47 |
. The following information will NOT be preserved: |
48 |
. global.account = AccountName |
49 |
. user.url = https://accounts.example.com |
50 |
. user.account = UserAccountName |
51 |
. compute.url = https://cyclades.example.com/api/v1.1 |
52 |
. file.url = https://pithos.example.com/v1 |
53 |
. image.url = https://cyclades.example.com/plankton |
54 |
. store.account = OldForgotenAccountName |
55 |
. Kamaki is ready to convert the config file |
56 |
. Create (overwrite) file .kamakirc.okeanos ? [y/N] |
57 |
. |
58 |
<y is pressed> |
59 |
. |
60 |
. No cloud "default" is configured |
61 |
. | To configure a new cloud "default", find and set the |
62 |
. | single authentication URL and token: |
63 |
. | kamaki config set cloud.default.url <URL> |
64 |
. | kamaki config set cloud.default.token <t0k3n> |
65 |
$ |
66 |
|
67 |
.. warning:: A new cloud configuration with the name "default" is created. The |
68 |
global token that was set in the old configuration file, is preserved as |
69 |
the token of the "default" cloud. Still, kamaki needs a url for the cloud |
70 |
and it encourages you to reset the token as well. |
71 |
|
72 |
.. note:: Some options are discarded. Among them, are the service urls, like |
73 |
user.url, compute.url, image.url and file.url . These settings are obsolete |
74 |
since Synnefo 0.14 and kamaki 0.9 so you do not need to recover them. The |
75 |
same is true for user accounts (retrieved automatically) |
76 |
|
77 |
.. note:: You can safely remove the global.XXX_cli options from kamaki |
78 |
configuration file. Kamaki can automatically resolve the default values for |
79 |
these internal options. These options are usefull when overloading the |
80 |
default command behaviors, but are not needed otherwise. |
81 |
|
82 |
Attempt to create a new configuration |
83 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
84 |
|
85 |
Ask kamaki to load from a non-existing configuration file |
86 |
|
87 |
.. code-block:: console |
88 |
|
89 |
$ kamaki -c nonexisting.cnf user authenticate |
90 |
. No cloud is configured |
91 |
. | To configure a new cloud "<cloud name>", find and set the |
92 |
. | single authentication URL and token: |
93 |
. | kamaki config set cloud.<cloud name>.url <URL> |
94 |
. | kamaki config set cloud.<cloud name>.token <t0k3n> |
95 |
$ ls -l nonexisting.cnf |
96 |
. ls: cannot access nonexisting.cnf: No such file or directory |
97 |
$ |
98 |
|
99 |
.. note:: configuration file is not created, but it will be when we set the |
100 |
first configuration value in it, as shown in the following subsection. |
101 |
|
102 |
Configure a cloud and create a new configuration |
103 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
104 |
|
105 |
Set the URL for new cloud "mytest" |
106 |
|
107 |
.. code-block:: console |
108 |
|
109 |
$ kamaki -c nonexisting.cnf config set cloud.mytest.url https://accounts.example.com/identity/v2.0/ |
110 |
|
111 |
Try to connect |
112 |
|
113 |
.. code-block:: console |
114 |
|
115 |
$ kamaki -c nonexisting.cnf user authenticate |
116 |
. No authentication token provided for cloud "mytest" |
117 |
. | Set a token for cloud mytest: |
118 |
. | kamaki config set cloud.mytest.token <token> |
119 |
|
120 |
Set token to cloud "mytest" |
121 |
|
122 |
.. code-block:: console |
123 |
|
124 |
$ kamaki -c nonexisting.cnf config set cloud.mytest.token myt35t70k3n== |
125 |
|
126 |
Check that the file is created, everything is set up correctly and working |
127 |
|
128 |
.. code-block:: console |
129 |
|
130 |
$ ls -l nonexisting.cnf |
131 |
. -rw------- 1 someuser someuser 491 Jun 17 13:39 nonexisting.cnf |
132 |
$ kamaki -c nonexisting.cnf config get cloud |
133 |
. cloud.mytest.url = https://accounts.example.com/identity/v2.0/ |
134 |
. cloud.mytest.token = myt35t70k3n== |
135 |
$ kamaki -c nonexisting.cnf user autenticate |
136 |
. ... |
137 |
. user: |
138 |
. id: s0me-3x4mp13-u53r-1d |
139 |
. name: Some User |
140 |
. roles: |
141 |
. id: 1 |
142 |
. name: default |
143 |
. roles_links: |
144 |
$ |
145 |
|
146 |
Failed or incomplete cloud configurations |
147 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
148 |
|
149 |
Now let kamaki use the default configuration ( ${HOME}/.kamakirc ). Let the old |
150 |
token be `my0ld70k3n==` and let it be invalid. |
151 |
|
152 |
Check for clouds and attempt to authenticate |
153 |
|
154 |
.. code-block:: console |
155 |
|
156 |
$ kamaki config get cloud |
157 |
. cloud.default.token = my0ld70k3n== |
158 |
$ kamaki user authenticate |
159 |
. No authentication URL provided for cloud "mytest" |
160 |
. | Set a URL for cloud mytest: |
161 |
. | kamaki config set cloud.mytest.url <URL> |
162 |
$ |
163 |
|
164 |
Set a non-existing URL for cloud.default and attempt authentication |
165 |
|
166 |
.. code-block:: console |
167 |
|
168 |
$ kamaki config set cloud.default.url https://nonexisting.example.com |
169 |
$ kamaki user authenticate |
170 |
. Failed while http-connecting to https://nonexisting.example.com |
171 |
$ |
172 |
|
173 |
Set the URL from the previous example and attempt authentication |
174 |
|
175 |
.. code-block:: console |
176 |
|
177 |
$ kamaki config set cloud.default.url https://accounts.example.com/identity/v2.0/ |
178 |
$ kamaki user authenticate |
179 |
. (401) Authorization failed for token gZH99orgkfYHmGksZKvHJw== |
180 |
. | UNAUTHORIZED unauthorized (Invalid token) |
181 |
$ |
182 |
|
183 |
After some searching at the deployments UI, you found out that the URL/token |
184 |
pair you need is:: |
185 |
|
186 |
URL: https://accounts.deploymentexample.com/identity/v2.0 |
187 |
TOKEN: myd3pl0ym3nt70k3n== |
188 |
|
189 |
Set up the correct values and attempt authentication |
190 |
|
191 |
.. code-block:: console |
192 |
|
193 |
$ kamaki config set cloud.default.url https://accounts.deploymentexample.com/identity/v2.0 |
194 |
$ kamaki config set cloud.default.token myd3pl0ym3nt70k3n== |
195 |
$ kamaki user authenticate |
196 |
. ... |
197 |
. user: |
198 |
. id: my-d3pl0ym3nt-u53r-1d |
199 |
. name: Example Username |
200 |
$ |
201 |
|
202 |
Multiple clouds in a single configuration |
203 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
204 |
|
205 |
We now have two configurations:: |
206 |
|
207 |
Configuration file: ${HOME}/.kamakirc (default) |
208 |
Clouds: |
209 |
ALIAS: default |
210 |
URL: https://accounts.deploymentexample.com/identity/v2.0 |
211 |
TOKEN: myd3pl0ym3nt70k3n== |
212 |
|
213 |
Copnfiguration file: nonexisting.cnf |
214 |
Clouds: |
215 |
ALIAS: mytest |
216 |
URL: https://accounts.example.com/identity/v2.0/ |
217 |
TOKEN: myt35t70k3n== |
218 |
|
219 |
As we can see, the default configuration handles only one cloud, aliased as |
220 |
"default". We will add the second cloud as well. |
221 |
|
222 |
.. code-block:: console |
223 |
|
224 |
$ kamaki config set cloud.mytest.url https://accounts.example.com/identity/v2.0/ |
225 |
$ kamaki config set cloud.mytest.token myt35t70k3n== |
226 |
$ |
227 |
|
228 |
Check all clouds |
229 |
|
230 |
.. code-block:: console |
231 |
|
232 |
$ kamaki config get cloud |
233 |
. cloud.default.url = https://accounts.deploymentexample.com/identity/v2.0/ |
234 |
. cloud.default.token = myd3pl0ym3nt70k3n== |
235 |
. cloud.mytest.url = https://accounts.example.com/identity/v2.0/ |
236 |
. cloud.mytest.token = myt35t70k3n== |
237 |
$ |
238 |
|
239 |
Check if kamaki knows one of the clouds to be the default |
240 |
|
241 |
.. code-block:: console |
242 |
|
243 |
$ kamaki config get default_cloud |
244 |
. default |
245 |
$ |
246 |
|
247 |
Authenticate against different clouds |
248 |
|
249 |
.. code-block:: console |
250 |
|
251 |
$ kamaki user authenticate |
252 |
. ... |
253 |
. <response from deploymentexample.com> |
254 |
. ... |
255 |
$ kamaki --cloud=mytest user authenticate |
256 |
. ... |
257 |
. <response from example.com> |
258 |
. ... |
259 |
$ kamaki --cloud=default user authenticate |
260 |
. ... |
261 |
. <response from deploymentexample.com, same as default behavior> |
262 |
. ... |
263 |
$ kamaki --cloud=nonexistingcloud user authenticate |
264 |
. No cloud "nonexistingcloud" is configured |
265 |
. | To configure a new cloud "nonexistingcloud", find and set the |
266 |
. | single authentication URL and token: |
267 |
. | kamaki config set cloud.nonexistingcloud.url <URL> |
268 |
. | kamaki config set cloud.nonexistingcloud.token <t0k3n> |
269 |
$ |
270 |
|
271 |
Confuse kamaki by removing the default_cloud option, set mytest as default |
272 |
|
273 |
.. code-block:: console |
274 |
|
275 |
$ kamaki config delete default_cloud |
276 |
$ kamaki user authenticate |
277 |
. Found 2 clouds but none of them is set as default |
278 |
. | Please, choose one of the following cloud names: |
279 |
. | default, mytest |
280 |
. | To set a default cloud: |
281 |
. | kamaki config set default_cloud <cloud name> |
282 |
$ kamaki config set default_cloud mytest |
283 |
$ kamaki user authenticate |
284 |
. ... |
285 |
. <response from example.com> |
286 |
. ... |
287 |
$ |
288 |
|
289 |
`Question`: What will happen if the "default" cloud alias **and** the |
290 |
default_cloud option are removed? |
291 |
|
292 |
.. code-block:: console |
293 |
|
294 |
$ kamaki config delete cloud.default |
295 |
$ kamaki config delete default_cloud |
296 |
$ kamaki user authenticate |
297 |
. ... |
298 |
. <response from example.com> |
299 |
. ... |
300 |
$ |
301 |
|
302 |
`Answer`: kamaki doesn't have a default_cloud option, but there is only one |
303 |
cloud configuration (`mytest`), therefore there is no ambiguity in resolving |
304 |
the default cloud. |
305 |
|
306 |
Multiple configurations |
307 |
^^^^^^^^^^^^^^^^^^^^^^^ |
308 |
|
309 |
In the following example, a user wants to experiment with upload and download |
310 |
for different number of threads. The plan is to contuct a set of tests with 3 |
311 |
threads at most and another one with 5. All experiments will be run against the |
312 |
same Synnefo cloud (the "mytest" cloud from the previous example). |
313 |
|
314 |
Let's create the 3-threaded configuration first |
315 |
|
316 |
.. code-block:: console |
317 |
|
318 |
$ kamaki -c 3thread config set cloud.test.url https://accounts.example.com/identity/v2.0/ |
319 |
$ kamaki -c 3thread config set cloud.test.token myt35t70k3n== |
320 |
$ |
321 |
|
322 |
Let's set the max_thread option to 3 as well as a seperate file for logs. |
323 |
|
324 |
.. code-block:: console |
325 |
|
326 |
$ kamaki -c 3thread config set max_thread 3 |
327 |
$ kamaki -c 3thread config log_file ./logs/kamaki.3threads.log |
328 |
$ |
329 |
|
330 |
Now, let's create the 5-threaded configuration by modifying a copy of 3thread |
331 |
|
332 |
.. code-block:: console |
333 |
|
334 |
$ cp 3thread 5thread |
335 |
$ kamaki -c 5thread config set max_thread 5 |
336 |
$ kamaki -c 5thread config log_file ./logs/kamaki.5threads.log |
337 |
$ |
338 |
|
339 |
Use kamaki to upload with 3 threads and 5 threads respectively |
340 |
|
341 |
.. code-block:: console |
342 |
|
343 |
$ kamaki -c 3thread file upload testfiles/test1 testcontainer |
344 |
$ kamaki -c 5thread file upload testfiles/test1 testcontainer |
345 |
$ |
346 |
|
347 |
List |
348 |
---- |
349 |
|
350 |
Simple listing |
351 |
^^^^^^^^^^^^^^ |
352 |
|
353 |
Detailed listing |
354 |
^^^^^^^^^^^^^^^^ |
355 |
|
356 |
Filtered listing |
357 |
^^^^^^^^^^^^^^^^ |
358 |
|
359 |
Upload and download |
360 |
------------------- |
361 |
|
362 |
Upload a file, download an object |
363 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
364 |
|
365 |
Recursive upload (directory) |
366 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
367 |
|
368 |
Recursive download (path prefix) |
369 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
370 |
|
371 |
Publish and share |
372 |
----------------- |
373 |
|
374 |
Check permissions |
375 |
^^^^^^^^^^^^^^^^^ |
376 |
|
377 |
Publish |
378 |
^^^^^^^ |
379 |
|
380 |
Share with users and groups |
381 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
382 |
|
383 |
Share with all |
384 |
^^^^^^^^^^^^^^ |
385 |
|
386 |
Shared with me |
387 |
-------------- |
388 |
|
389 |
Users who share objects with me |
390 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
391 |
|
392 |
List shared objects |
393 |
^^^^^^^^^^^^^^^^^^^ |
394 |
|
395 |
Copy shared objects |
396 |
^^^^^^^^^^^^^^^^^^^ |
397 |
|
398 |
Image register |
399 |
-------------- |
400 |
|
401 |
Upload and register image |
402 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
403 |
|
404 |
Register with metadata template |
405 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
406 |
|
407 |
Upload and register multiple images |
408 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
409 |
|
410 |
virtual machines |
411 |
---------------- |
412 |
|
413 |
Create a server |
414 |
^^^^^^^^^^^^^^^ |
415 |
|
416 |
Inject ssh keys |
417 |
^^^^^^^^^^^^^^^ |
418 |
|
419 |
Inject user profiles |
420 |
^^^^^^^^^^^^^^^^^^^^ |
421 |
|
422 |
Connect and disconnect to a network |
423 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
424 |
|
425 |
Networks |
426 |
-------- |
427 |
|
428 |
Create a private network |
429 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
430 |
|
431 |
Connect VMs on it |
432 |
^^^^^^^^^^^^^^^^^ |
433 |
|
434 |
Destroy a private network |
435 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |