|
1 |
Image registration
|
|
2 |
==================
|
|
3 |
|
|
4 |
In Synnefo, an image is loaded as a file to the storage service (Pithos+), and
|
|
5 |
then is registered to the image service (Plankton). The image location at the
|
|
6 |
storage server is unique through out a deployment and also necessary for the
|
|
7 |
image to exist.
|
|
8 |
|
|
9 |
The image location format::
|
|
10 |
|
|
11 |
pithos://<user id>/<container>/<object path>
|
|
12 |
|
|
13 |
e.g.:
|
|
14 |
|
|
15 |
pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
|
|
16 |
|
|
17 |
|
|
18 |
Register an image
|
|
19 |
-----------------
|
|
20 |
|
|
21 |
Let the image file `debian_base3.diskdump` be a debian image located at the
|
|
22 |
current directory.
|
|
23 |
|
|
24 |
Upload the image to container `pithos`
|
|
25 |
|
|
26 |
.. code-block:: console
|
|
27 |
|
|
28 |
[kamaki]: file upload debian_base3.diskdump pithos
|
|
29 |
Uploading /home/someuser/debian_base3.diskdump --> pithos:debian_base3.diskdump
|
|
30 |
Done
|
|
31 |
[kamaki]:
|
|
32 |
|
|
33 |
Register the image object with the name 'Debian Base Alpha'
|
|
34 |
|
|
35 |
.. code-block:: console
|
|
36 |
|
|
37 |
[kamaki]: image register 'Debian Base Alpha' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
|
|
38 |
checksum: 3cb03556ec971f...e8dd6190443b560cb7
|
|
39 |
container-format: bare
|
|
40 |
created-at: 2013-06-19 08:00:22
|
|
41 |
deleted-at:
|
|
42 |
disk-format: diskdump
|
|
43 |
id: 7h1rd-1m4g3-1d
|
|
44 |
is-public: False
|
|
45 |
location: pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
|
|
46 |
name: Debian Base Alpha
|
|
47 |
owner: s0m3-u53r-1d
|
|
48 |
properties:
|
|
49 |
size: 903471104
|
|
50 |
status: available
|
|
51 |
updated-at: 2013-06-19 08:01:00
|
|
52 |
Metadata file uploaded as pithos:debian_base3.diskdump.meta (version 1352)
|
|
53 |
[kamaki]:
|
|
54 |
|
|
55 |
.. note:: The `image register` command automatically create a meta file and
|
|
56 |
uploads it to the same location as the image. The meta file can be
|
|
57 |
downloaded and reused for more image registrations.
|
|
58 |
|
|
59 |
Read the metafile
|
|
60 |
|
|
61 |
.. code-block:: console
|
|
62 |
|
|
63 |
[kamaki]: file cat pithos:debian_base3.diskdump
|
|
64 |
{
|
|
65 |
"status": "available",
|
|
66 |
"name": "Debian Base Gama",
|
|
67 |
"checksum": "3cb03556ec971f...e8dd6190443b560cb7",
|
|
68 |
"id": "7h1rd-1m4g3-1d2",
|
|
69 |
"updated-at": "2013-06-19 08:01:00",
|
|
70 |
"created-at": "2013-06-19 08:00:22",
|
|
71 |
"properties": {},
|
|
72 |
"location": "pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump",
|
|
73 |
"is-public": "False",
|
|
74 |
"owner": "s0m3-u53r-1d",
|
|
75 |
"disk-format": "diskdump",
|
|
76 |
"size": "903471104",
|
|
77 |
"deleted-at": "",
|
|
78 |
"container-format": "bare"
|
|
79 |
}
|
|
80 |
[kamaki]:
|
|
81 |
|
|
82 |
Images registered by me
|
|
83 |
-----------------------
|
|
84 |
|
|
85 |
List all images, then list only images owned by the user with id s0m3-u53r-1d
|
|
86 |
|
|
87 |
.. code-block:: console
|
|
88 |
|
|
89 |
[kamaki]: image list
|
|
90 |
f1r57-1m4g3-1d Debian Base Alpha
|
|
91 |
container_format: bare
|
|
92 |
disk_format: diskdump
|
|
93 |
size: 474066944
|
|
94 |
status: available
|
|
95 |
53c0nd-1m4g3-1d Beta Debian Base
|
|
96 |
container_format: bare
|
|
97 |
disk_format: diskdump
|
|
98 |
size: 474066944
|
|
99 |
status: available
|
|
100 |
7h1rd-1m4g3-1d Debian Base Gama
|
|
101 |
container_format: bare
|
|
102 |
disk_format: diskdump
|
|
103 |
size: 474066944
|
|
104 |
status: available
|
|
105 |
[kamaki]: image list --owner=s0m3-u53r-1d
|
|
106 |
7h1rd-1m4g3-1d Debian Base Gama
|
|
107 |
container_format: bare
|
|
108 |
disk_format: diskdump
|
|
109 |
size: 474066944
|
|
110 |
status: available
|
|
111 |
[kamaki]:
|
|
112 |
|
|
113 |
.. note:: To get the current user id, use `user authenticate` in kamaki
|
|
114 |
|
|
115 |
Unregister an image
|
|
116 |
-------------------
|
|
117 |
|
|
118 |
An image can be unregistered by its image id, but only if the current user is
|
|
119 |
also the image owner. In this example, there is only one image owned by current
|
|
120 |
user.
|
|
121 |
|
|
122 |
Unregister image owned by current user
|
|
123 |
|
|
124 |
.. code-block:: console
|
|
125 |
|
|
126 |
[kamaki]: image unregister 7h1rd-1m4g3-1d
|
|
127 |
[kamaki]:
|
|
128 |
|
|
129 |
Check if the image is deleted
|
|
130 |
|
|
131 |
.. code-block:: console
|
|
132 |
|
|
133 |
[kamaki]: image list --owner=s0m3-u53r-1d
|
|
134 |
[kamaki]:
|
|
135 |
|
|
136 |
Attempt to unregister an image of another user
|
|
137 |
|
|
138 |
.. code-block:: console
|
|
139 |
|
|
140 |
[kamaki]: image unregister f1r57-1m4g3-1d
|
|
141 |
(403) FORBIDDEN forbidden ()
|
|
142 |
[kamaki]:
|
|
143 |
|
|
144 |
Register with properties
|
|
145 |
------------------------
|
|
146 |
|
|
147 |
The image will be registered again, but with some custom properties::
|
|
148 |
|
|
149 |
OS: Linux
|
|
150 |
user: someuser
|
|
151 |
|
|
152 |
These properties can be added freely by the user, and they have no significance
|
|
153 |
for the image server, but they could be used to help using the image more
|
|
154 |
efficiently.
|
|
155 |
|
|
156 |
Attempt to register with properties
|
|
157 |
|
|
158 |
.. code-block:: console
|
|
159 |
|
|
160 |
[kamaki]: image register 'Debian Base Gama' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump -p OS=Linux -p user=someuser
|
|
161 |
Metadata file pithos:debian_base3.diskdump.meta already exists
|
|
162 |
[kamaki]:
|
|
163 |
|
|
164 |
It's true that the metafile is already there, but we can override it (**-f**)
|
|
165 |
|
|
166 |
.. code-block:: console
|
|
167 |
|
|
168 |
[kamaki]: image register -f 'Debian Base Gama' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump -p OS=Linux -p user=someuser
|
|
169 |
[kamaki]:
|
|
170 |
|
|
171 |
Register with a meta file
|
|
172 |
-------------------------
|
|
173 |
|
|
174 |
Download the meta file of the image (it was uploaded recently)
|
|
175 |
|
|
176 |
.. code-block:: console
|
|
177 |
|
|
178 |
[kamaki]: file download pithos:debian_base3.diskdump.meta
|
|
179 |
Downloading pithos:debian_base3.diskdump.meta --> /home/someuser/debian_base3.diskdump.meta
|
|
180 |
Done
|
|
181 |
[kamaki]:
|
|
182 |
|
|
183 |
The metadata file can be edited. Let's edit the file, by adding properties::
|
|
184 |
|
|
185 |
OS: Linux
|
|
186 |
user: root
|
|
187 |
|
|
188 |
The resulting file will look like this:
|
|
189 |
|
|
190 |
.. code-block:: javascript
|
|
191 |
|
|
192 |
{
|
|
193 |
"status": "available",
|
|
194 |
"name": "Debian Base Gama",
|
|
195 |
"checksum": "3cb03556ec971f...e8dd6190443b560cb7",
|
|
196 |
"id": "7h1rd-1m4g3-1d2",
|
|
197 |
"updated-at": "2013-06-19 08:01:00",
|
|
198 |
"created-at": "2013-06-19 08:00:22",
|
|
199 |
"properties": {
|
|
200 |
"OS": "Linux",
|
|
201 |
"USER": "root"
|
|
202 |
},
|
|
203 |
"location": "pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump",
|
|
204 |
"is-public": "False",
|
|
205 |
"owner": "s0m3-u53r-1d",
|
|
206 |
"disk-format": "diskdump",
|
|
207 |
"size": "903471104",
|
|
208 |
"deleted-at": "",
|
|
209 |
"container-format": "bare"
|
|
210 |
}
|
|
211 |
|
|
212 |
.. warning:: make sure the file is in a valid json format, otherwise image
|
|
213 |
register will fail
|
|
214 |
|
|
215 |
In the following registration, a different name will be used for the image.
|
|
216 |
|
|
217 |
Register the image (don't forget the -f parameter, to override the metafile).
|
|
218 |
|
|
219 |
.. code-block:: console
|
|
220 |
|
|
221 |
[kamaki]: image register -f 'Debian Base Delta' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump --metafile=debian_base3.diskdump.meta
|
|
222 |
checksum: 3cb03556ec971f...e8dd6190443b560cb7
|
|
223 |
container-format: bare
|
|
224 |
created-at: 2013-06-19 08:00:22
|
|
225 |
deleted-at:
|
|
226 |
disk-format: diskdump
|
|
227 |
id: 7h1rd-1m4g3-1d
|
|
228 |
is-public: False
|
|
229 |
location: pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
|
|
230 |
name: Debian Base Delta
|
|
231 |
owner: s0m3-u53r-1d
|
|
232 |
properties:
|
|
233 |
OS: Linux
|
|
234 |
USER: root
|
|
235 |
size: 903471104
|
|
236 |
status: available
|
|
237 |
updated-at: 2013-06-19 08:01:00
|
|
238 |
Metadata file uploaded as pithos:debian_base3.diskdump.meta (version 1359)
|
|
239 |
[kamaki]:
|
|
240 |
|
|
241 |
Reregistration: priorities and overrides
|
|
242 |
----------------------------------------
|
|
243 |
|
|
244 |
Let's review the examples presented above::
|
|
245 |
|
|
246 |
- Register an image with name `Debian Base Gama`
|
|
247 |
- Unregister the image
|
|
248 |
- Register a new image of the uploaded image object, with custom properties
|
|
249 |
- Reregister the image with a meta file and modified properties and name
|
|
250 |
|
|
251 |
**The image id is related to the image object**
|
|
252 |
|
|
253 |
Although the image was unregistered and reregistered, the image id, that is
|
|
254 |
produced automatically at the server side, was the same. This is due to the
|
|
255 |
fact that image ids are 1 to 1 related to image objects uploaded to Pithos+
|
|
256 |
|
|
257 |
**An explicit name overrides the metafile**
|
|
258 |
|
|
259 |
Each image needs a name and this is given as the first argument of the
|
|
260 |
`register` command. This name overrides the name in the metafile.
|
|
261 |
|
|
262 |
**Reregistration is not update, but an override**
|
|
263 |
|
|
264 |
The property `user: root` won over `user: someuser`, because it was set last.
|
|
265 |
Actually, all properties were replaced by the new ones, when the image was
|
|
266 |
reregistered, and the same holds with all customizable attributes of the image.
|
|
267 |
|
|
268 |
Command line wins the metafile
|
|
269 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
270 |
|
|
271 |
Let's compine the metafile with a command line attribute `user: admin`
|
|
272 |
|
|
273 |
.. code-block:: console
|
|
274 |
|
|
275 |
[kamaki]: image register -f 'Debian Base Delta' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump --metafile=debian_base3.diskdump.meta
|
|
276 |
checksum: 3cb03556ec971f...e8dd6190443b560cb7
|
|
277 |
container-format: bare
|
|
278 |
created-at: 2013-06-19 08:00:22
|
|
279 |
deleted-at:
|
|
280 |
disk-format: diskdump
|
|
281 |
id: 7h1rd-1m4g3-1d
|
|
282 |
is-public: False
|
|
283 |
location: pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
|
|
284 |
name: Debian Base Delta
|
|
285 |
owner: s0m3-u53r-1d
|
|
286 |
properties:
|
|
287 |
OS: Linux
|
|
288 |
USER: root
|
|
289 |
size: 903471104
|
|
290 |
status: available
|
|
291 |
updated-at: 2013-06-19 08:01:00
|
|
292 |
Metadata file uploaded as pithos:debian_base3.diskdump.meta (version 1377)
|
|
293 |
[kamaki]:
|
|
294 |
|
|
295 |
Although the property `OS` was read from the metafile, the property `USER` was
|
|
296 |
set by the command line property to `admin`.
|
|
297 |
|
|
298 |
.. note:: This feature allows the use of a metafile as a template for uploading
|
|
299 |
multiple images with many common attributes but slight modifications per
|
|
300 |
image
|
|
301 |
|
|
302 |
Multiple metafile versions
|
|
303 |
--------------------------
|
|
304 |
|
|
305 |
.. warning:: Make sure your container is set to auto, otherwise, there will be
|
|
306 |
no object versions
|
|
307 |
|
|
308 |
.. code-block:: console
|
|
309 |
|
|
310 |
[kamaki]: file versioning get pithos
|
|
311 |
x-container-policy-versioning: auto
|
|
312 |
[kamaki]:
|
|
313 |
|
|
314 |
To set versioning to auto
|
|
315 |
|
|
316 |
.. code-block:: console
|
|
317 |
|
|
318 |
[kamaki]: file versioning set auto pithos
|
|
319 |
[kamaki]:
|
|
320 |
|
|
321 |
In the above examples, the image was registered many times by overriding the
|
|
322 |
metafile. It is possible to avoid writing a metafile, as well as accessing
|
|
323 |
older versions of the file.
|
|
324 |
|
|
325 |
Register the image without uploading a metafile
|
|
326 |
|
|
327 |
.. code-block:: console
|
|
328 |
|
|
329 |
[kamaki]: image register 'Debian Base Delta' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump --metafile=debian_base3.diskdump.meta --no-metafile-upload
|
|
330 |
checksum: 3cb03556ec971f...e8dd6190443b560cb7
|
|
331 |
container-format: bare
|
|
332 |
created-at: 2013-06-19 08:00:22
|
|
333 |
deleted-at:
|
|
334 |
disk-format: diskdump
|
|
335 |
id: 7h1rd-1m4g3-1d
|
|
336 |
is-public: False
|
|
337 |
location: pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
|
|
338 |
name: Debian Base Delta
|
|
339 |
owner: s0m3-u53r-1d
|
|
340 |
properties:
|
|
341 |
OS: Linux
|
|
342 |
USER: root
|
|
343 |
size: 903471104
|
|
344 |
status: available
|
|
345 |
updated-at: 2013-06-19 08:01:00
|
|
346 |
[kamaki]:
|
|
347 |
|
|
348 |
Uploaded metafiles are kept in versions, thanks to Pithos+ versioning support
|
|
349 |
|
|
350 |
.. code-block:: console
|
|
351 |
|
|
352 |
[kamaki]: file versions pithos:debian_base3.diskdump.meta
|
|
353 |
1352
|
|
354 |
created: 19-06-2013 11:00:22
|
|
355 |
1359
|
|
356 |
created: 19-06-2013 11:01:00
|
|
357 |
1377
|
|
358 |
created: 19-06-2013 11:34:37
|
|
359 |
[kamaki]:
|
|
360 |
|
|
361 |
Consult the first version of the metafile
|
|
362 |
|
|
363 |
.. code-block:: console
|
|
364 |
|
|
365 |
[kamaki]: file cat --object-version=1352 pithos:debian_base3.diskdump.meta
|
|
366 |
{
|
|
367 |
"status": "available",
|
|
368 |
"name": "Debian Base Gama",
|
|
369 |
"checksum": "3cb03556ec971f...e8dd6190443b560cb7",
|
|
370 |
"id": "7h1rd-1m4g3-1d2",
|
|
371 |
"updated-at": "2013-06-19 08:01:00",
|
|
372 |
"created-at": "2013-06-19 08:00:22",
|
|
373 |
"properties": {},
|
|
374 |
"location": "pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump",
|
|
375 |
"is-public": "False",
|
|
376 |
"owner": "s0m3-u53r-1d",
|
|
377 |
"disk-format": "diskdump",
|
|
378 |
"size": "903471104",
|
|
379 |
"deleted-at": "",
|
|
380 |
"container-format": "bare"
|
|
381 |
}
|
|
382 |
[kamaki]:
|
|
383 |
|
|
384 |
Download the second version
|
|
385 |
|
|
386 |
.. code-block:: console
|
|
387 |
|
|
388 |
[kamaki]: file download --object-version=1359 pithos:debian_base3.diskdump.meta debian_base3.diskdump.meta.v1359
|
|
389 |
Downloading pithos:debian_base3.diskdump.meta --> /home/someuser/debian_base3.diskdump.meta.v1359
|
|
390 |
Done
|
|
391 |
[kamaki]:
|
|
392 |
|
|
393 |
Batch image upload
|
|
394 |
------------------
|
|
395 |
|
|
396 |
Let a directory at /home/someuser/images with a variety of images needed to be
|
|
397 |
uploaded and registered.
|
|
398 |
|
|
399 |
Batch-upload the images
|
|
400 |
|
|
401 |
.. code-block:: console
|
|
402 |
|
|
403 |
[kamaki]: file upload -R images pithos
|
|
404 |
mkdir pithos:images
|
|
405 |
Uploading /home/someuser/images/debian.diskdump --> pithos:images/debian.diskdump
|
|
406 |
Uploading /home/someuser/images/win8.diskdump --> pithos:images/win8.diskdump
|
|
407 |
...
|
|
408 |
Done
|
|
409 |
[kamaki]:
|
|
410 |
|
|
411 |
Make sure the images are uploaded to pithos:images/ remote directory object
|
|
412 |
|
|
413 |
.. code-block:: console
|
|
414 |
|
|
415 |
[kamaki]: file list pithos:images/
|
|
416 |
D images/
|
|
417 |
983MB images/debian.diskdump
|
|
418 |
2.2GB images/win8.diskdump
|
|
419 |
...
|
|
420 |
[kamaki]:
|
|
421 |
|
|
422 |
Use the host shell capabilities to streamline the registration, so exit kamaki
|
|
423 |
|
|
424 |
.. code-block:: console
|
|
425 |
|
|
426 |
[kamaki]: /exit
|
|
427 |
|
|
428 |
The following is a bash script that attempts to register the already uploaded
|
|
429 |
images:
|
|
430 |
|
|
431 |
.. code-block:: bash
|
|
432 |
|
|
433 |
#!/bin/bash
|
|
434 |
|
|
435 |
userid=... # e.g. s0m3-u53r-1d
|
|
436 |
container=... # e.g. pithos
|
|
437 |
|
|
438 |
for path in images/*.diskdump; do
|
|
439 |
location=pithos://$userid/$container/${path}
|
|
440 |
kamaki image register $path $location
|
|
441 |
done
|
|
442 |
|
|
443 |
Let's use the script (enriched with a separator message) to batch-register the
|
|
444 |
images (all images will be named after their relative paths).
|
|
445 |
|
|
446 |
Also, let the registered images be public (accessible to all users for creating
|
|
447 |
VMs) by adding the **--public** flag argument when calling `image register`.
|
|
448 |
|
|
449 |
.. code-block:: console
|
|
450 |
|
|
451 |
$ for path in images/*.diskdump; do
|
|
452 |
location=pithos://s0m3-u53r-1d/pithos/${path}
|
|
453 |
echo "- - - Register ${path} - - -"
|
|
454 |
kamaki image register $path $location --public
|
|
455 |
done
|
|
456 |
- - - Register images/debian.diskdump ---
|
|
457 |
checksum: 3cb03556ec971f...e8dd6190443b560cb7
|
|
458 |
container-format: bare
|
|
459 |
created-at: 2013-06-19 08:00:22
|
|
460 |
deleted-at:
|
|
461 |
disk-format: diskdump
|
|
462 |
id: d3b14n-1m4g3-1d
|
|
463 |
is-public: False
|
|
464 |
location: pithos://s0m3-u53r-1d/pithos/images/debian.diskdump
|
|
465 |
name: images/debian.diskdump
|
|
466 |
owner: s0m3-u53r-1d
|
|
467 |
properties:
|
|
468 |
size: 903471104
|
|
469 |
status: available
|
|
470 |
updated-at: 2013-06-19 08:01:00
|
|
471 |
Metadata file uploaded as pithos:images/debian.diskdump.meta (version 4201)
|
|
472 |
- - - Register images/win8.diskdump ---
|
|
473 |
checksum: 4cb03556ec971f...e8dd6190443b560cb6
|
|
474 |
container-format: bare
|
|
475 |
created-at: 2013-06-19 08:00:22
|
|
476 |
deleted-at:
|
|
477 |
disk-format: diskdump
|
|
478 |
id: w1nd0w5-1m4g3-1d
|
|
479 |
is-public: False
|
|
480 |
location: pithos://s0m3-u53r-1d/pithos/images/win8.diskdump
|
|
481 |
name: images/win8.diskdump
|
|
482 |
owner: s0m3-u53r-1d
|
|
483 |
properties:
|
|
484 |
size: 2103471104
|
|
485 |
status: available
|
|
486 |
updated-at: 2013-06-19 08:01:00
|
|
487 |
Metadata file uploaded as pithos:images/debian.diskdump.meta (version 4301)
|
|
488 |
...
|
|
489 |
$
|
|
490 |
|
|
491 |
.. note:: All images can be re-registered, either individually or with a batch
|
|
492 |
process.
|
|
493 |
|
|
494 |
|