code.grnet.gr Git - kamaki/blob - docs/collection_of_examples/imageregister.rst

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