Statistics
| Branch: | Tag: | Revision:

root / docs / examplesdir / imageregister.rst @ a54bd720

History | View | Annotate | Download (16.5 kB)

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 in each a deployment and also a key for identifying
7
the image.
8

    
9
The image location format at user level::
10

    
11
    pithos://<user_uuid>/<container>/<object path>
12

    
13
    e.g., pithos://my-u53r-1d/images/debian_base3.diskdump
14

    
15
In **file** and **container** contexts, users may also use the shortcut:
16

    
17
    /<container>/<object path>
18

    
19
    e.g., /images/debian_base3.diskdump
20

    
21

    
22
Register an image
23
-----------------
24

    
25
Let the image file `debian_base3.diskdump` be a debian image located at the
26
current local directory.
27

    
28
Upload the image to container `images`
29

    
30
.. code-block:: console
31

    
32
    $ kamaki file upload debian_base3.diskdump /images
33

    
34
Register the image object with the name 'Debian Base Alpha'
35

    
36
.. code-block:: console
37

    
38
    kamaki image register --name 'Debian Base Alpha' --location=/images/debian_base3.diskdump
39
    checksum:         3cb03556ec971f...e8dd6190443b560cb7
40
    container-format: bare
41
    created-at:       2013-06-19 08:00:22
42
    deleted-at:
43
    disk-format:      diskdump
44
    id:               7h1rd-1m4g3-1d
45
    is-public:        False
46
    location:         pithos://s0m3-u53r-1d/images/debian_base3.diskdump
47
    name:             Debian Base Alpha
48
    owner:            s0m3-u53r-1d
49
    properties:
50
    size:             903471104
51
    status:           available
52
    updated-at:       2013-06-19 08:01:00
53
    Metadata file uploaded as /images/debian_base3.diskdump.meta (version 1352)
54

    
55
.. warning:: The image created by the above command will not be able to create
56
    a working virtual server, although the registration will be successful. In
57
    the synnefo universe, an image has to be registered along with some
58
    `properties <http://www.synnefo.org/docs/snf-image/latest/usage.html#image-properties>`_.
59

    
60
.. note:: The `image register` command automatically creates a meta file and
61
    uploads it to the same location as the image. The meta file can be
62
    downloaded and reused for more image registrations.
63

    
64
Here is another way to perform the two operations above: **/image register**
65
with the **\- -upload-image-file** argument. This single operation will upload
66
the image file and then register it as an image, and is equivalent to
67
sequentially calling **/file upload** and **/image register**.
68

    
69
In other words, the preceding and following command sequences are equivalent.
70

    
71
.. code-block:: console
72

    
73
        kamaki image register --name='Debian Base Alpha'
74
            --location=/images/debian_base3.diskdump
75
            --upload-image-file=debian_base3.diskdump
76

    
77

    
78
Read the metafile
79

    
80
.. code-block:: console
81

    
82
    kamaki file cat /images/debian_base3.diskdump.meta
83
    {
84
      "status": "available",
85
      "name": "Debian Base Gama",
86
      "checksum": "3cb03556ec971f...e8dd6190443b560cb7",
87
      "id": "7h1rd-1m4g3-1d2",
88
      "updated-at": "2013-06-19 08:01:00",
89
      "created-at": "2013-06-19 08:00:22",
90
      "properties": {},
91
      "location": "pithos://s0m3-u53r-1d/images/debian_base3.diskdump",
92
      "is-public": "False",
93
      "owner": "s0m3-u53r-1d",
94
      "disk-format": "diskdump",
95
      "size": "903471104",
96
      "deleted-at": "",
97
      "container-format": "bare"
98
    }
99

    
100
Images registered by me
101
-----------------------
102

    
103
List all images, then list only images owned by the user with id s0m3-u53r-1d
104

    
105
.. code-block:: console
106

    
107
    kamaki image list
108
    f1r57-1m4g3-1d Debian Base Alpha
109
        container_format: bare
110
        disk_format:      diskdump
111
        size:             474066944
112
        status:           available
113
    53c0nd-1m4g3-1d Beta Debian Base
114
        container_format: bare
115
        disk_format:      diskdump
116
        size:             474066944
117
        status:           available
118
    7h1rd-1m4g3-1d Debian Base Gama
119
        container_format: bare
120
        disk_format:      diskdump
121
        size:             474066944
122
        status:           available
123
    kamaki image list --owner=s0m3-u53r-1d
124
    7h1rd-1m4g3-1d Debian Base Gama
125
        container_format: bare
126
        disk_format:      diskdump
127
        size:             474066944
128
        status:           available
129

    
130
.. note:: To get the current user id, use `kamaki user info`
131

    
132
Unregister an image
133
-------------------
134

    
135
An image can be unregistered by its image id, but only if the current user is
136
also the image owner. In this example, there is only one image owned by current
137
user.
138

    
139
Unregister image owned by current user
140

    
141
.. code-block:: console
142

    
143
    kamaki image unregister 7h1rd-1m4g3-1d
144

    
145
Check if the image is deleted
146

    
147
.. code-block:: console
148

    
149
    kamaki image list --owner=s0m3-u53r-1d
150

    
151
Attempt to unregister an image of another user
152

    
153
.. code-block:: console
154

    
155
    kamaki image unregister f1r57-1m4g3-1d
156
    (403) FORBIDDEN forbidden ()
157

    
158
Register with properties
159
------------------------
160

    
161
.. warning:: A succesfully registered image will not be functional, if the
162
    image properties are not defined correctly. Read the
163
    `documentation <http://www.synnefo.org/docs/snf-image/latest/usage.html#image-properties>`_
164
    for more information.
165

    
166
The image will be registered again, but with some custom properties::
167

    
168
    OSFAMILY: linux
169
    USER: someuser
170

    
171
In theory, these properties can be added freely by the user, and they are not
172
required by the image server. In practice, some properties are absolutely
173
vital for an image to be useful, although not necessary for registration.
174
An attempt to register an image with custom properties:
175

    
176
.. code-block:: console
177

    
178
    kamaki image register --name='Debian Base Gama' --location=/images/debian_base3.diskdump -p OS=linux -p user=someuser
179
    Metadata file /images/debian_base3.diskdump.meta already exists
180

    
181
It's true that a metafile with this name is already there, but we can override
182
it (**-f**)
183

    
184
.. code-block:: console
185

    
186
    kamaki image register -f --name='Debian Base Gama' --location=/images/debian_base3.diskdump -p OS=linux -p user=someuser
187

    
188
Register with a meta file
189
-------------------------
190

    
191
Download the meta file of the image (it was uploaded recently)
192

    
193
.. code-block:: console
194

    
195
    kamaki file download /images/debian_base3.diskdump.meta
196
    Downloading /images/debian_base3.diskdump.meta --> /home/someuser/debian_base3.diskdump.meta
197
    Done
198

    
199
The metadata file can be edited. Let's edit the file to add these properties::
200

    
201
    OS: linux
202
    USER: root
203

    
204
The resulting file will look like this:
205

    
206
.. code-block:: javascript
207

    
208
    {
209
      "status": "available",
210
      "name": "Debian Base Gama",
211
      "checksum": "3cb03556ec971f...e8dd6190443b560cb7",
212
      "id": "7h1rd-1m4g3-1d2",
213
      "updated-at": "2013-06-19 08:01:00",
214
      "created-at": "2013-06-19 08:00:22",
215
      "properties": {
216
        "OS": "linux",
217
        "USER": "root"
218
      },
219
      "location": "pithos://s0m3-u53r-1d/images/debian_base3.diskdump",
220
      "is-public": "False",
221
      "owner": "s0m3-u53r-1d",
222
      "disk-format": "diskdump",
223
      "size": "903471104",
224
      "deleted-at": "",
225
      "container-format": "bare"
226
    }
227

    
228
.. warning:: make sure the file is in a valid json format, otherwise image
229
    register will fail
230

    
231
In the following registration, the image name will change to a new one.
232

    
233
Register the image (don't forget the -f parameter, to override the metafile).
234

    
235
.. code-block:: console
236

    
237
    kamaki image register -f --name='Debian Base Delta' --location=/images/debian_base3.diskdump --metafile=debian_base3.diskdump.meta
238
    checksum:         3cb03556ec971f...e8dd6190443b560cb7
239
    container-format: bare
240
    created-at:       2013-06-19 08:00:22
241
    deleted-at:
242
    disk-format:      diskdump
243
    id:               7h1rd-1m4g3-1d
244
    is-public:        False
245
    location:         pithos://s0m3-u53r-1d/images/debian_base3.diskdump
246
    name:             Debian Base Delta
247
    owner:            s0m3-u53r-1d
248
    properties:
249
            OS:     linux
250
            USER:   root
251
    size:             903471104
252
    status:           available
253
    updated-at:       2013-06-19 08:01:00
254
    Metadata file uploaded as /images/debian_base3.diskdump.meta (version 1359)
255

    
256
Metadata and Property modification
257
----------------------------------
258

    
259
According to the OpenStack terminology, the terms **metadata** and
260
**properties** are two different thinks, if we talk about images. **Metadata**
261
are all kinds of named metadata on an image. Some of them are assigned by the
262
system, some others are custom and set by the users who register the image.
263
These custom **metadata** are called **properties**.
264

    
265
Image **metadata** and custom **properties** can be modified even after the
266
image is registered. Metadata are fixed image attributes, like name, disk
267
format etc. while custom properties are set by the image owner and, usually,
268
refer to attributes of the images OS.
269

    
270
Let's rename the image:
271

    
272
.. code-block:: console
273

    
274
    kamaki image modify 7h1rd-1m4g3-1d --name='Changed Name'
275

    
276
A look at the image metadata reveals that the name is changed:
277

    
278
.. code-block:: console
279

    
280
    kamaki image info 7h1rd-1m4g3-1d
281
    checksum:         3cb03556ec971f...e8dd6190443b560cb7
282
    container-format: bare
283
    created-at:       2013-06-19 08:00:22
284
    deleted-at:
285
    disk-format:      diskdump
286
    id:               7h1rd-1m4g3-1d
287
    is-public:        False
288
    location:         pithos://s0m3-u53r-1d/images/debian_base3.diskdump
289
    name:             Changed Name
290
    owner:            s0m3-u53r-1d
291
    properties:
292
            OS:     linux
293
            USER:   root
294
    size:             903471104
295
    status:           available
296
    updated-at:       2013-06-19 08:01:00
297
    kamaki
298

    
299
We can use the same idea to change the values of other metadata like disk
300
format, container format or status. On the other hand, we cannot modify the
301
id, owner, location, checksum and dates. e.g., to make an image public or
302
private:
303

    
304
.. code-block:: console
305

    
306
    kamaki image modify 7h1rd-1m4g3-1d --public --name='Debian Base Gama'
307
    kamaki image modify 7h1rd-1m4g3-1d --private
308

    
309
The first call publishes the image (set is-public to True) and also restores
310
the name to "Debian Base Gama". The second one unpublishes the image (set
311
is-public to False).
312

    
313
These operations can be used for properties with the same semantics:
314

    
315
.. code-block:: console
316

    
317
    kamaki image modify 7h1rd-1m4g3-1d -p user=user
318
    kamaki image info 7h1rd-1m4g3-1d
319
    ...
320
    properties:
321
            OS:     linux
322
            USER:   user
323
    ...
324
    kamaki
325

    
326
Just to test the feature, let's create a property "greet" with value
327
"hi there", and then remove it. Also, let's restore the value of USER:
328

    
329
.. code-block:: console
330

    
331
    kamaki image modify 7h1rd-1m4g3-1d -p greet='Hi there' -p user=root
332
    kamaki image info 7h1rd-1m4g3-1d
333
    ...
334
    properties:
335
            OS:     linux
336
            USER:   root
337
            GREET:  Hi there
338
    ...
339
    kamaki image modify 7h1rd-1m4g3-1d --property-del greet
340
    kamaki image info 7h1rd-1m4g3-1d
341
    ...
342
    properties:
343
            OS:     linux
344
            USER:   root
345
    ...
346
    kamaki
347

    
348

    
349
Reregistration: priorities and overrides
350
----------------------------------------
351

    
352
Let's review the examples presented above::
353

    
354
    - Register an image with name `Debian Base Gama`
355
    - Unregister the image
356
    - Register a new image of the uploaded image object, with custom properties
357
    - Reregister the image with a meta file and modified properties and name
358

    
359
**The image id is related to the image object**
360

    
361
Although the image was unregistered and reregistered, the image id, that is
362
produced automatically at the server side, was the same. This is due to the
363
fact that image ids are 1 to 1 related to image objects uploaded to Pithos+
364

    
365
**An explicit image name overrides the metafile**
366

    
367
Each image needs a name and this is given as the first argument of the
368
`register` command. This name overrides the name in the metafile.
369

    
370
**Reregistration is not an update, but an override**
371

    
372
The property `user: root` won over `user: someuser`, because it was set last.
373
Actually, all properties were replaced by the new ones, when the image was
374
reregistered, and the same holds with all customizable attributes of the image.
375

    
376
Command line wins the metafile
377
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
378

    
379
Let's compine the metafile with a command line attribute `user: admin`
380

    
381
.. code-block:: console
382

    
383
    kamaki image register -f --name='Debian Base Delta' --location=/images/debian_base3.diskdump --metafile=debian_base3.diskdump.meta
384
    checksum:         3cb03556ec971f...e8dd6190443b560cb7
385
    container-format: bare
386
    created-at:       2013-06-19 08:00:22
387
    deleted-at:
388
    disk-format:      diskdump
389
    id:               7h1rd-1m4g3-1d
390
    is-public:        False
391
    location:         pithos://s0me-u53r/images/s0m3-u53r-1d/images/debian_base3.diskdump
392
    name:             Debian Base Delta
393
    owner:            s0m3-u53r-1d
394
    properties:
395
            OS:     linux
396
            USER:   root
397
    size:             903471104
398
    status:           available
399
    updated-at:       2013-06-19 08:01:00
400
    Metadata file uploaded as /images/debian_base3.diskdump.meta (version 1377)
401
    kamaki
402

    
403
Although the property `OS` was read from the metafile, the property `USER` was
404
set by the command line property to `admin`.
405

    
406
.. note:: This feature allows the use of a metafile as a template for uploading
407
    multiple images with many common attributes but slight modifications per
408
    image
409

    
410
Multiple metafile versions
411
--------------------------
412

    
413
.. warning:: Make sure your container is set to auto, otherwise, there will be
414
    no object versions
415

    
416
    .. code-block:: console
417

    
418
        kamaki container info images | grep versioning
419
        x-container-policy-versioning: auto
420

    
421
    To set versioning to auto
422

    
423
    .. code-block:: console
424

    
425
        kamaki container modify images --versioning=auto
426

    
427
In the above examples, the image was registered many times by overriding the
428
metafile. It is possible to avoid writing a metafile, as well as accessing
429
older versions of the file.
430

    
431
Register the image without uploading a metafile
432

    
433
.. code-block:: console
434

    
435
    kamaki image register --name='Debian Base Delta' --location=/images/debian_base3.diskdump --metafile=debian_base3.diskdump.meta --no-metafile-upload
436
    checksum:         3cb03556ec971f...e8dd6190443b560cb7
437
    container-format: bare
438
    created-at:       2013-06-19 08:00:22
439
    deleted-at:
440
    disk-format:      diskdump
441
    id:               7h1rd-1m4g3-1d
442
    is-public:        False
443
    location:         pithos://s0m3-u53r/images/s0m3-u53r-1d/images/debian_base3.diskdump
444
    name:             Debian Base Delta
445
    owner:            s0m3-u53r-1d
446
    properties:
447
            OS:     linux
448
            USER:   root
449
    size:             903471104
450
    status:           available
451
    updated-at:       2013-06-19 08:01:00
452
    kamaki
453

    
454
Uploaded metafiles are kept in versions, thanks to Pithos+ versioning support
455

    
456
.. code-block:: console
457

    
458
    kamaki file info /images/debian_base3.diskdump.meta --object-versions
459
    1352
460
     created: 19-06-2013 11:00:22
461
    1359
462
     created: 19-06-2013 11:01:00
463
    1377
464
     created: 19-06-2013 11:34:37
465
    kamaki
466

    
467
Consult the first version of the metafile
468

    
469
.. code-block:: console
470

    
471
    kamaki file cat --object-version=1352 /images/debian_base3.diskdump.meta
472
    {
473
      "status": "available",
474
      "name": "Debian Base Gama",
475
      "checksum": "3cb03556ec971f...e8dd6190443b560cb7",
476
      "id": "7h1rd-1m4g3-1d2",
477
      "updated-at": "2013-06-19 08:01:00",
478
      "created-at": "2013-06-19 08:00:22",
479
      "properties": {},
480
      "location": "pithos://s0m3-u53r/images/s0m3-u53r-1d/images/debian_base3.diskdump",
481
      "is-public": "False",
482
      "owner": "s0m3-u53r-1d",
483
      "disk-format": "diskdump",
484
      "size": "903471104",
485
      "deleted-at": "",
486
      "container-format": "bare"
487
    }
488

    
489
Download the second version
490

    
491
.. code-block:: console
492

    
493
    kamaki file download --object-version=1359 /images/debian_base3.diskdump.meta debian_base3.diskdump.meta.v1359
494
    Downloading /images/debian_base3.diskdump.meta --> /home/someuser/debian_base3.diskdump.meta.v1359
495
    Done
496

    
497
Batch image upload
498
------------------
499

    
500
Let a directory at /home/someuser/images with a variety of images needed to be
501
uploaded and registered.
502

    
503
Batch-upload the images
504

    
505
.. code-block:: console
506

    
507
    kamaki file upload -r images /images
508
    mkdir /images/images
509
    Uploading /home/someuser/images/debian.diskdump --> /images/images/debian.diskdump
510
    Uploading /home/someuser/images/win8.diskdump --> /images/images/win8.diskdump
511
    ...
512
    Done
513

    
514
Make sure the images are uploaded to /images/images/ remote directory object
515

    
516
.. code-block:: console
517

    
518
    kamaki file list /images/images/
519
    D       images/
520
    983MB   images/debian.diskdump
521
    2.2GB   images/win8.diskdump
522
    ...
523
    kamaki
524

    
525
Use the host shell capabilities to streamline the registration, so exit kamaki
526

    
527
.. code-block:: console
528

    
529
    kamaki /exit