root / docs / plankton-api-guide.rst @ 9f41ab1e
History | View | Annotate | Download (35 kB)
| 1 |
.. _plankton-api-guide: |
|---|---|
| 2 |
|
| 3 |
Cyclades/Image API Guide |
| 4 |
======================== |
| 5 |
|
| 6 |
Introduction |
| 7 |
------------ |
| 8 |
|
| 9 |
The Image Service of `Synnefo <http://www.synnefo.org>`_ is implemented as part |
| 10 |
of Cyclades. It exposes the OpenStack `Glance API |
| 11 |
<http://docs.openstack.org/developer/glance/glanceapi.html>`_, with minor |
| 12 |
changes or additions wherever needed. |
| 13 |
|
| 14 |
This document's goals are: |
| 15 |
|
| 16 |
* Define the Cyclades/Image ReST API |
| 17 |
* Clarify the differences between Cyclades/Image and Glance |
| 18 |
|
| 19 |
Image ReST API |
| 20 |
-------------- |
| 21 |
========================================= ===================================== ====== ======== ====== |
| 22 |
Description URI Method Image Glance |
| 23 |
========================================= ===================================== ====== ======== ====== |
| 24 |
`List Available Images <#id2>`_ ``/images`` GET ✔ ✔ |
| 25 |
`List Available Images in Detail <#id3>`_ ``/images/detail`` GET ✔ ✔ |
| 26 |
`Add or update an Image <#id6>`_ ``/images`` POST ✔ ✔ |
| 27 |
`Update an Image <#id9>`_ ``/images`` PUT **✘** ✔ |
| 28 |
\ ``/images/<img-id>`` PUT ✔ **✘** |
| 29 |
`Retrieve Image Metadata <#id10>`_ ``/images/<img-id>`` HEAD ✔ ✔ |
| 30 |
`Retrieve Raw Image Data <#id12>`_ ``/images/<img-id>`` GET **✘** ✔ |
| 31 |
`List Image Memberships <#id14>`_ ``/images/<img-id>/members`` GET ✔ ✔ |
| 32 |
`Replace a Membership List <#id15>`_ ``/images/<img-id>/members`` PUT ✔ ✔ |
| 33 |
`Add a Member to an Image <#id16>`_ ``/images/<img-id>/members/<member>`` PUT ✔ ✔ |
| 34 |
`Remove a Member from an Image <#id17>`_ ``/images/<img-id>/members/<member>`` DELETE ✔ ✔ |
| 35 |
`List Shared Images <#id19>`_ ``/shared-images/<member>`` GET ✔ ✔ |
| 36 |
========================================= ===================================== ====== ======== ====== |
| 37 |
|
| 38 |
Authentication |
| 39 |
-------------- |
| 40 |
|
| 41 |
**Image** depends on Astakos to handle authentication of clients. An |
| 42 |
authentication token must be obtained from the identity manager which should be |
| 43 |
send along with each API requests through the *X-Auth-Token* header. Image |
| 44 |
handles the communication with Astakos to verify the token validity and obtain |
| 45 |
identity credentials. |
| 46 |
|
| 47 |
**Glance** handles authentication in a `similar manner |
| 48 |
<http://docs.openstack.org/developer/glance/glanceapi.html#authentication>`_, |
| 49 |
with the only difference being the suggested identity manager. |
| 50 |
|
| 51 |
|
| 52 |
List Available Images |
| 53 |
--------------------- |
| 54 |
|
| 55 |
This request returns a list of all images accessible by the user. In specific, |
| 56 |
the list contains images falling at one of the following categories: |
| 57 |
|
| 58 |
* registered by the user |
| 59 |
* shared to user by others |
| 60 |
* public |
| 61 |
|
| 62 |
=========== ====== ======== ====== |
| 63 |
URI Method Image Glance |
| 64 |
=========== ====== ======== ====== |
| 65 |
``/images`` GET ✔ ✔ |
| 66 |
=========== ====== ======== ====== |
| 67 |
|
| 68 |
| |
| 69 |
|
| 70 |
====================== ======================================= ======== ====== |
| 71 |
Request Parameter Name Value Image Glance |
| 72 |
====================== ======================================= ======== ====== |
| 73 |
name Return images of given name ✔ ✔ |
| 74 |
container_format Return images of given container format ✔ ✔ |
| 75 |
disk_format Return images of given disk format ✔ ✔ |
| 76 |
status Return images of given status ✔ ✔ |
| 77 |
size_min Return images of size >= to given value ✔ ✔ |
| 78 |
size_max Return images of size >= to given value ✔ ✔ |
| 79 |
sort_key Sort images against given key ✔ ✔ |
| 80 |
sort_dir Sort images in given direction ✔ ✔ |
| 81 |
====================== ======================================= ======== ====== |
| 82 |
|
| 83 |
**container_format** values are listed at :ref:`container-format-ref` |
| 84 |
|
| 85 |
**disk_format** values are listed at :ref:`disk-format-ref` |
| 86 |
|
| 87 |
**sort_key** values: id, name, status, size, disk_format, container_format, created_at, updated_at |
| 88 |
|
| 89 |
======== ================ ======== ======= |
| 90 |
sort_dir Description Image Glance |
| 91 |
======== ================ ======== ======= |
| 92 |
asc Ascending order default default |
| 93 |
desc Descending order ✔ ✔ |
| 94 |
======== ================ ======== ======= |
| 95 |
|
| 96 |
| |
| 97 |
|
| 98 |
==================== ========================= ======== ========= |
| 99 |
Request Header Name Value Image Glance |
| 100 |
==================== ========================= ======== ========= |
| 101 |
X-Auth-Token User authentication token required required |
| 102 |
==================== ========================= ======== ========= |
| 103 |
|
| 104 |
| |
| 105 |
|
| 106 |
=========================== ===================== |
| 107 |
Return Code Description |
| 108 |
=========================== ===================== |
| 109 |
200 (OK) The request succeeded |
| 110 |
400 (Bad Request) Raised in case of invalid values for |
| 111 |
\ *sort_key*, *sort_dir*, *size_max* or *size_min* |
| 112 |
401 (Unauthorized) Missing or expired user token |
| 113 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 114 |
=========================== ===================== |
| 115 |
|
| 116 |
The response data is a list of images in a json format containing the fields presented bellow |
| 117 |
|
| 118 |
================ ===================== ======== ====== |
| 119 |
Name Description Image Glance |
| 120 |
================ ===================== ======== ====== |
| 121 |
id A unique image id ✔ **✘** |
| 122 |
uri Unique id in URI form **✘** ✔ |
| 123 |
name The name of the image ✔ ✔ |
| 124 |
status The VM status ✔ **✘** |
| 125 |
disk_format The disc format ✔ ✔ |
| 126 |
container_format The container format ✔ ✔ |
| 127 |
size Image size in bytes ✔ ✔ |
| 128 |
================ ===================== ======== ====== |
| 129 |
|
| 130 |
Example Image response: |
| 131 |
|
| 132 |
:: |
| 133 |
|
| 134 |
[{
|
| 135 |
"status": "available", |
| 136 |
"name": "ubuntu", |
| 137 |
"disk_format": "diskdump", |
| 138 |
"container_format": "bare", |
| 139 |
"id": "5583ffe1-5273-4c84-9e32-2fbe476bd7b7", |
| 140 |
"size": 2622562304 |
| 141 |
}, {
|
| 142 |
"status": "available", |
| 143 |
"name": "Ubuntu-10.04", |
| 144 |
"disk_format": "diskdump", |
| 145 |
"container_format": "bare", |
| 146 |
"id": "907ef618-c03a-4473-9914-9348e12890c1", |
| 147 |
"size": 761368576 |
| 148 |
}] |
| 149 |
|
| 150 |
List Available Images in Detail |
| 151 |
------------------------------- |
| 152 |
|
| 153 |
This request returns the same list of images as in `List Available Images |
| 154 |
<#id2>`_, but the results are reacher in metadata. |
| 155 |
|
| 156 |
================== ====== ======== ====== |
| 157 |
URI Method Image Glance |
| 158 |
================== ====== ======== ====== |
| 159 |
``/images/detail`` GET ✔ ✔ |
| 160 |
================== ====== ======== ====== |
| 161 |
|
| 162 |
**Request parameters** and **headers** as well as **response headers** and |
| 163 |
**error codes** are exactly the same as in `List Available Images <#id2>`_, |
| 164 |
both syntactically and semantically. |
| 165 |
|
| 166 |
|
| 167 |
The response data is a list of images in json format containing the fields |
| 168 |
presented bellow |
| 169 |
|
| 170 |
================ ===================== ======== ====== |
| 171 |
Name Description Image Glance |
| 172 |
================ ===================== ======== ====== |
| 173 |
id A unique image id ✔ **✘** |
| 174 |
uri Unique id in URI form **✘** ✔ |
| 175 |
location Pithos file location ✔ **✘** |
| 176 |
name The name of the image ✔ ✔ |
| 177 |
status The Image status ✔ **✘** |
| 178 |
disk_format The disc format ✔ ✔ |
| 179 |
container_format The container format ✔ ✔ |
| 180 |
size Image size in bytes ✔ ✔ |
| 181 |
checksum file MD5 checksum ✔ ✔ |
| 182 |
created_at Timestamp of creation ✔ ✔ |
| 183 |
updated_at Timestamp of update ✔ ✔ |
| 184 |
deleted_at Timestamp of deletion ✔ ✔ |
| 185 |
is_public True if img is public ✔ ✔ |
| 186 |
min_ram Minimum ram required **✘** ✔ |
| 187 |
min_disk Maximum ram required **✘** ✔ |
| 188 |
owner Image owner ✔ ✔ |
| 189 |
properties Custom properties ✔ ✔ |
| 190 |
================ ===================== ======== ====== |
| 191 |
|
| 192 |
| |
| 193 |
|
| 194 |
Example Image response:: |
| 195 |
|
| 196 |
[{
|
| 197 |
"status": "available", |
| 198 |
"location": "pithos://u53r-1d/images/my/path/example_image_build.diskdump" |
| 199 |
"name": "ubuntu", |
| 200 |
"disk_format": "diskdump", |
| 201 |
"container_format": "bare", |
| 202 |
"created_at": "2013-03-29 14:14:34", |
| 203 |
"deleted_at": "", |
| 204 |
"id": "5583ffe1-5273-4c84-9e32-2fbe476bd7b7", |
| 205 |
"size": 2622562304, |
| 206 |
"is_public": "True", |
| 207 |
"checksum": "a387aaaae583bc65daacf12d6be502bd7cfbbb254dcd452f92ca31f4c06a9208", |
| 208 |
"properties": {
|
| 209 |
"partition_table": "msdos", |
| 210 |
"kernel": "3.8.3", |
| 211 |
"osfamily": "linux", |
| 212 |
"users": "root user", |
| 213 |
"gui": "GNOME 3.4.2", |
| 214 |
"sortorder": "5", |
| 215 |
"os": "fedora", |
| 216 |
"root_partition": "1", |
| 217 |
"description": "Fedora release 17 (Beefy Miracle)"} |
| 218 |
}, {
|
| 219 |
"location": "pithos://0th3r-u53r-1d/images/ubuntu_10_04.diskdump" |
| 220 |
"status": "available", |
| 221 |
"name": "Ubuntu-10.04", |
| 222 |
"disk_format": "diskdump", |
| 223 |
"container_format": "bare", |
| 224 |
"id": "907ef618-c03a-4473-9914-9348e12890c1", |
| 225 |
"size": 761368576 |
| 226 |
"created_at": "2013-03-29 14:14:34", |
| 227 |
"deleted_at": "" |
| 228 |
}] |
| 229 |
|
| 230 |
Add or update an image |
| 231 |
---------------------- |
| 232 |
|
| 233 |
According to the Synnefo approach, this request performs two operations: |
| 234 |
|
| 235 |
* registers a new image to Cyclades/Image |
| 236 |
* commits metadata for the new image |
| 237 |
* update the metadata of an existing image |
| 238 |
|
| 239 |
The physical image file must be uploaded on a `Pithos <pithos.html>`_ server, |
| 240 |
at a space accessible by the user. The Pithos location of the physical file |
| 241 |
acts as a key for the image (image ids and image locations are uniquely |
| 242 |
coupled). |
| 243 |
|
| 244 |
According to the OpenStack approach, this request performs the first two |
| 245 |
functionalities by uploading the the image data and metadata to Glance. In |
| 246 |
Glance, the update mechanism is not implemented with this specific request. |
| 247 |
|
| 248 |
=========== ====== ======== ====== |
| 249 |
URI Method Image Glance |
| 250 |
=========== ====== ======== ====== |
| 251 |
``/images`` POST ✔ ✔ |
| 252 |
=========== ====== ======== ====== |
| 253 |
|
| 254 |
| |
| 255 |
|
| 256 |
============================= ========================= ======== ======== |
| 257 |
Request Header Name Value Image Glance |
| 258 |
============================= ========================= ======== ======== |
| 259 |
X-Auth-Token User authentication token required required |
| 260 |
X-Image-Meta-Name Img name required required |
| 261 |
X-Image-Meta-Id Unique image id **✘** ✔ |
| 262 |
X-Image-Meta-Location img file location @Pithos required **✘** |
| 263 |
X-Image-Meta-Store Storage system ✔ ✔ |
| 264 |
X-Image-Meta-Disk-Format Img disk format ✔ **✘** |
| 265 |
X-Image-Meta-Disk_format Img disk format **✘** ✔ |
| 266 |
X-Image-Meta-Container-Format Container format ✔ **✘** |
| 267 |
X-Image-Meta-Container_format Container format **✘** ✔ |
| 268 |
X-Image-Meta-Size Size of img file ✔ ✔ |
| 269 |
X-Image-Meta-Checksum MD5 checksum of img file ✔ ✔ |
| 270 |
X-Image-Meta-Is-Public Make image public ✔ **✘** |
| 271 |
X-Image-Meta-Is_public Make image public **✘** ✔ |
| 272 |
x-image-meta-Min-Ram Minimum ram required (MB) **✘** ✔ |
| 273 |
x-image-meta-Min-Disk Maximum ram required (MB) **✘** ✔ |
| 274 |
X-Image-Meta-Owner Image owner ✔ ✔ |
| 275 |
X-Image-Meta-Property-* Property prefix ✔ ✔ |
| 276 |
============================= ========================= ======== ======== |
| 277 |
|
| 278 |
**X-Meta-Location** format is described at :ref:`location-ref` |
| 279 |
|
| 280 |
**X-Image-Meta-Id** is explained at :ref:`id-ref` |
| 281 |
|
| 282 |
**X-Image-Meta-Store** values are listed at :ref:`store-ref` |
| 283 |
|
| 284 |
**X-Image-Meta-Disk-Format** values are listed at :ref:`disk-format-ref` |
| 285 |
|
| 286 |
**X-Image-Meta-Container-Format** values are listed at :ref:`container-format-ref` |
| 287 |
|
| 288 |
**X-Image-Meta-Size** is optional, but should much the actual image file size. |
| 289 |
|
| 290 |
**X-Image-Meta-Is-Public** values are true or false (case insensitive) |
| 291 |
|
| 292 |
**X-Image-Meta-Property-*** is used as a prefix to set custom, free-form key:value properties on an image, e.g.:: |
| 293 |
|
| 294 |
X-Image-Meta-Property-OS: Debian Linux |
| 295 |
X-Image-Meta-Property-Users: Root |
| 296 |
|
| 297 |
| |
| 298 |
|
| 299 |
=========================== ===================== |
| 300 |
Return Code Description |
| 301 |
=========================== ===================== |
| 302 |
200 (OK) The request succeeded |
| 303 |
400 (Bad Request) |
| 304 |
\ No name header |
| 305 |
\ Illegal header value |
| 306 |
\ File not found on given location |
| 307 |
\ Invalid size or checksum |
| 308 |
401 (Unauthorized) Missing or expired user token |
| 309 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 310 |
501 (Not Implemented) Location header is empty or omitted |
| 311 |
=========================== ===================== |
| 312 |
|
| 313 |
| |
| 314 |
|
| 315 |
The following is used when the response code is 200: |
| 316 |
|
| 317 |
============================= ===================== ======== ====== |
| 318 |
Response Header Description Image Glance |
| 319 |
============================= ===================== ======== ====== |
| 320 |
X-Image-Meta-Id Unique img id ✔ **✘** |
| 321 |
X-Image-Meta-Name Img name ✔ **✘** |
| 322 |
X-Image-Meta-Disk-Format Disk format ✔ **✘** |
| 323 |
X-Image-Meta-Container-Format Container format ✔ **✘** |
| 324 |
X-Image-Meta-Size Img file size ✔ **✘** |
| 325 |
X-Image-Meta-Checksum Img file MD5 checksum ✔ **✘** |
| 326 |
X-Image-Meta-Location Pithos file location ✔ **✘** |
| 327 |
X-Image-Meta-Created-At Date of img creation ✔ **✘** |
| 328 |
X-Image-Meta-Deleted-At Date of img deletion ✔ **✘** |
| 329 |
X-Image-Meta-Status Img status ✔ **✘** |
| 330 |
X-Image-Meta-Is-Public True if img is public ✔ **✘** |
| 331 |
X-Image-Meta-Owner Img owner or tentant ✔ **✘** |
| 332 |
X-Image-Meta-Property-* Custom img properties ✔ **✘** |
| 333 |
============================= ===================== ======== ====== |
| 334 |
|
| 335 |
Update an Image |
| 336 |
--------------- |
| 337 |
|
| 338 |
In Cyclades/Image, an image can be updated either by re-registering with |
| 339 |
different metadata, or by using the request described in the present |
| 340 |
subsection. |
| 341 |
|
| 342 |
In Glance, an update is implemented as a *PUT* request on ``/images`` URI. The |
| 343 |
method described bellow is not part of the Glance API. |
| 344 |
|
| 345 |
====================== ====== ======== ====== |
| 346 |
URI Method Image Glance |
| 347 |
====================== ====== ======== ====== |
| 348 |
``/images`` PUT **✘** ✔ |
| 349 |
``/images/<image-id>`` PUT ✔ **✘** |
| 350 |
====================== ====== ======== ====== |
| 351 |
|
| 352 |
The following refers only to the Cyclades/Image implementation. |
| 353 |
|
| 354 |
**image-id** is explained at :ref:`id-ref` |
| 355 |
|
| 356 |
| |
| 357 |
|
| 358 |
============================= ========================= |
| 359 |
Request Header Name Value |
| 360 |
============================= ========================= |
| 361 |
X-Auth-Token User authentication token |
| 362 |
X-Image-Meta-Name New image name |
| 363 |
X-Image-Meta-Disk-Format New disk format |
| 364 |
X-Image-Meta-Container-Format New container format |
| 365 |
X-Image-Meta-Status New image status |
| 366 |
X-Image-Meta-Is-Public (un)publish the image |
| 367 |
X-Image-Meta-Owner Set an owner |
| 368 |
X-Image-Meta-Property-* Add / modify properties |
| 369 |
============================= ========================= |
| 370 |
|
| 371 |
**X-Image-Meta-Disk-Format** values are listed at :ref:`disk-format-ref` |
| 372 |
|
| 373 |
**X-Image-Meta-Container-Format** values are listed at :ref:`container-format-ref` |
| 374 |
|
| 375 |
**X-Image-Meta-Size** is optional, but should much the actual image file size. |
| 376 |
|
| 377 |
**X-Image-Meta-Is-Public** values are true or false (case insensitive) |
| 378 |
|
| 379 |
**X-Image-Meta-Property-*** is used as a prefix to update image property |
| 380 |
values, or set some extra proeperties. If a registered image already contains |
| 381 |
some custom properties that are not addressed in the update request, these |
| 382 |
properties will remain untouched. For example:: |
| 383 |
|
| 384 |
X-Image-Meta-Property-OS: Debian Linux |
| 385 |
X-Image-Meta-Property-Users: Root |
| 386 |
|
| 387 |
| |
| 388 |
|
| 389 |
=========================== ===================== |
| 390 |
Return Code Description |
| 391 |
=========================== ===================== |
| 392 |
200 (OK) The request succeeded |
| 393 |
400 (Bad Request) |
| 394 |
\ Illegal header value |
| 395 |
\ Invalid size or checksum |
| 396 |
401 (Unauthorized) Missing or expired user token |
| 397 |
404 (Not found) Image not found |
| 398 |
405 (Not allowed) Current user does not have permission to change the image |
| 399 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 400 |
=========================== ===================== |
| 401 |
|
| 402 |
| |
| 403 |
|
| 404 |
The following is received when the response code is 200: |
| 405 |
|
| 406 |
============================= ===================== |
| 407 |
Response Header Description |
| 408 |
============================= ===================== |
| 409 |
X-Image-Meta-Id Unique img id |
| 410 |
X-Image-Meta-Name Img name |
| 411 |
X-Image-Meta-Disk-Format Disk format |
| 412 |
X-Image-Meta-Container-Format Container format |
| 413 |
X-Image-Meta-Size Img file size |
| 414 |
X-Image-Meta-Checksum Img file MD5 checksum |
| 415 |
X-Image-Meta-Location Pithos file location |
| 416 |
X-Image-Meta-Created-At Date of img creation |
| 417 |
X-Image-Meta-Deleted-At Date of img deletion |
| 418 |
X-Image-Meta-Status Img status |
| 419 |
X-Image-Meta-Is-Public True if img is public |
| 420 |
X-Image-Meta-Owner Img owner or tentant |
| 421 |
X-Image-Meta-Property-* Custom img properties |
| 422 |
============================= ===================== |
| 423 |
|
| 424 |
.. hint:: In Cyclades/Image, use POST to completely reset all image properties |
| 425 |
and metadata, but use PUT to update a few values without affecting the |
| 426 |
rest. |
| 427 |
|
| 428 |
Retrieve Image Metadata |
| 429 |
----------------------- |
| 430 |
|
| 431 |
This request returns the metadata of an image. Images are identified by their |
| 432 |
unique image id. |
| 433 |
|
| 434 |
In a typical scenario, client applications would query the server to `List |
| 435 |
Available Images <#id2>`_ for them and then choose one of the image ids |
| 436 |
returned. |
| 437 |
|
| 438 |
====================== ====== ======== ====== |
| 439 |
URI Method Image Glance |
| 440 |
====================== ====== ======== ====== |
| 441 |
``/images/<image-id>`` HEAD ✔ ✔ |
| 442 |
====================== ====== ======== ====== |
| 443 |
|
| 444 |
**image-id** is explained at :ref:`id-ref` |
| 445 |
|
| 446 |
| |
| 447 |
|
| 448 |
==================== ========================= ======== ========= |
| 449 |
Request Header Name Value Image Glance |
| 450 |
==================== ========================= ======== ========= |
| 451 |
X-Auth-Token User authentication token required required |
| 452 |
==================== ========================= ======== ========= |
| 453 |
|
| 454 |
| |
| 455 |
|
| 456 |
=========================== ===================== |
| 457 |
Return Code Description |
| 458 |
=========================== ===================== |
| 459 |
200 (OK) The request succeeded |
| 460 |
401 (Unauthorized) Missing or expired user token |
| 461 |
404 (Not Found) Image not found |
| 462 |
405 (Not Allowed) Access to that image is not allowed |
| 463 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 464 |
=========================== ===================== |
| 465 |
|
| 466 |
| |
| 467 |
|
| 468 |
============================= ===================== ======== ====== |
| 469 |
Response Header Description Image Glance |
| 470 |
============================= ===================== ======== ====== |
| 471 |
X-Image-Meta-Id Unique img id ✔ ✔ |
| 472 |
X-Image-Meta-Location Pithos file location ✔ **✘** |
| 473 |
X-Image-Meta-URI URI of image file **✘** ✔ |
| 474 |
X-Image-Meta-Name Img name ✔ ✔ |
| 475 |
X-Image-Meta-Disk-Format Disk format ✔ **✘** |
| 476 |
X-Image-Meta-Disk_format Disk format **✘** ✔ |
| 477 |
X-Image-Meta-Container-Format Container format ✔ **✘** |
| 478 |
X-Image-Meta-Container_format Container format **✘** ✔ |
| 479 |
X-Image-Meta-Size Img file size ✔ ✔ |
| 480 |
X-Image-Meta-Checksum Img file MD5 checksum ✔ ✔ |
| 481 |
X-Image-Meta-Created-At Date of img creation ✔ **✘** |
| 482 |
X-Image-Meta-Created_At Date of img creation **✘** ✔ |
| 483 |
X-Image-Meta-Updated-At Last modification ✔ **✘** |
| 484 |
X-Image-Meta-Updated_At Last modification **✘** ✔ |
| 485 |
X-Image-Meta-Deleted-At Date of img deletion ✔ **✘** |
| 486 |
X-Image-Meta-Deleted_At Date of img deletion **✘** ✔ |
| 487 |
X-Image-Meta-Status Img status ✔ ✔ |
| 488 |
X-Image-Meta-Is-Public True if img is public ✔ ✔ |
| 489 |
X-Image-Meta-Min-Ram Minimum image RAM **✘** ✔ |
| 490 |
X-Image-Meta-Min-Disk Minimum disk size **✘** ✔ |
| 491 |
X-Image-Meta-Owner Img owner or tentant ✔ ✔ |
| 492 |
X-Image-Meta-Property-* Custom img properties ✔ ✔ |
| 493 |
============================= ===================== ======== ====== |
| 494 |
|
| 495 |
**X-Image-Created-At** is the (immutable) date of initial registration, while |
| 496 |
**X-Image-Meta-Updated-At** indicates the date of last modification of the |
| 497 |
image (if any). |
| 498 |
|
| 499 |
**X-Image-Meta-Store** values are listed at :ref:`store-ref` |
| 500 |
|
| 501 |
**X-Image-Meta-Disk-Format** values are listed at :ref:`disk-format-ref` |
| 502 |
|
| 503 |
**X-Image-Meta-Container-Format** values are listed at |
| 504 |
:ref:`container-format-ref` |
| 505 |
|
| 506 |
**X-Image-Meta-Is-Public** values are true or false (case insensitive) |
| 507 |
|
| 508 |
**X-Image-Meta-Property-*** is used as a prefix to set custom, free-form |
| 509 |
key:value properties on an image, e.g.:: |
| 510 |
|
| 511 |
X-Image-Meta-Property-OS: Debian Linux |
| 512 |
X-Image-Meta-Property-Users: Root |
| 513 |
|
| 514 |
Example Cyclades/Image Headers response:: |
| 515 |
|
| 516 |
x-image-meta-id: 940509eb-eb4f-496c-8443-22ffd24912e9 |
| 517 |
x-image-meta-location: pithos://25cced7-bd53-4145-91ee-cf4737e9fb2/images/some-image.diskdump |
| 518 |
x-image-meta-name: Debian Desktop |
| 519 |
x-image-meta-disk-format: diskdump |
| 520 |
x-image-meta-container-format: bare |
| 521 |
x-image-meta-size: 3399127040 |
| 522 |
x-image-meta-checksum: d0f28e4d72927c90eadf30917d94d0156781fe1351ed16402b538316d404 |
| 523 |
x-image-meta-created-at: 2013-02-26 12:04:31 |
| 524 |
x-image-meta-updated-at: 2013-02-26 12:05:28 |
| 525 |
x-image-meta-deleted-at: |
| 526 |
x-image-meta-status: available |
| 527 |
x-image-meta-is-public: True |
| 528 |
x-image-meta-owner: 25cced7-bd53-4145-91ee-cf4737e9fb2 |
| 529 |
x-image-meta-property-partition-table: msdos |
| 530 |
x-image-meta-property-osfamily: linux |
| 531 |
x-image-meta-property-sortorder: 2 |
| 532 |
x-image-meta-property-description: Debian 6.0.7 (Squeeze) Desktop |
| 533 |
x-image-meta-property-os: debian |
| 534 |
x-image-meta-property-users: root user |
| 535 |
x-image-meta-property-kernel: 2.6.32 |
| 536 |
x-image-meta-property-root-partition: 1 |
| 537 |
x-image-meta-property-gui: GNOME 2.30.2 |
| 538 |
|
| 539 |
Retrieve Raw Image Data |
| 540 |
----------------------- |
| 541 |
|
| 542 |
In **Image**, the raw image data is stored at a `Pithos <pithos.html>`_ |
| 543 |
server and it can be downloaded from the Pithos web UI, with a `client |
| 544 |
<https://okeanos.grnet.gr/services/pithos/>`_ or with `kamaki |
| 545 |
<http://www.synnefo.org/docs/kamaki/latest/index.html>`_. The location of an |
| 546 |
image file can be retrieved from the *X-Image-Meta-Location* header field (see |
| 547 |
`Retrieve Image Meta <#id10>`_) |
| 548 |
|
| 549 |
In **Glance**, the raw image can be downloaded with a GET request on |
| 550 |
``/images/<image-id>``. |
| 551 |
|
| 552 |
List Image Memberships |
| 553 |
---------------------- |
| 554 |
|
| 555 |
This request returns the list of users who can access an image. Cyclades/Image |
| 556 |
returns an empty list if the image is publicly accessible. |
| 557 |
|
| 558 |
============================== ====== ======== ====== |
| 559 |
URI Method Image Glance |
| 560 |
============================== ====== ======== ====== |
| 561 |
``/images/<image-id>/members`` GET ✔ ✔ |
| 562 |
============================== ====== ======== ====== |
| 563 |
|
| 564 |
**image-id** is explained at :ref:`id-ref` |
| 565 |
|
| 566 |
| |
| 567 |
|
| 568 |
==================== ========================= ======== ========= |
| 569 |
Request Header Name Value Image Glance |
| 570 |
==================== ========================= ======== ========= |
| 571 |
X-Auth-Token User authentication token required required |
| 572 |
==================== ========================= ======== ========= |
| 573 |
|
| 574 |
| |
| 575 |
|
| 576 |
=========================== ===================== |
| 577 |
Return Code Description |
| 578 |
=========================== ===================== |
| 579 |
200 (OK) The request succeeded |
| 580 |
401 (Unauthorized) Missing or expired user token |
| 581 |
404 (Not Found) Image not found |
| 582 |
405 (Not Allowed) Access to that image is not allowed |
| 583 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 584 |
=========================== ===================== |
| 585 |
|
| 586 |
| |
| 587 |
|
| 588 |
The response data is a list of users (members) who can access this image |
| 589 |
|
| 590 |
================ ===================== ======== ====== |
| 591 |
Name Description Image Glance |
| 592 |
================ ===================== ======== ====== |
| 593 |
member_id uuid (user id) ✔ ✔ |
| 594 |
can_share Member can share img false ✔ |
| 595 |
================ ===================== ======== ====== |
| 596 |
|
| 597 |
**can_share** in Cyclades/Image is always false and is returned for |
| 598 |
compatibility reasons. |
| 599 |
|
| 600 |
Example Cyclades/Image response:: |
| 601 |
|
| 602 |
{'members': [
|
| 603 |
{'member_id': 'th15-4-u53r-1d-fr0m-p1th05',
|
| 604 |
'can_share': false}, |
| 605 |
... |
| 606 |
]} |
| 607 |
|
| 608 |
Replace a Membership List |
| 609 |
------------------------- |
| 610 |
|
| 611 |
This request replaces the list of users who can access a registered image. The |
| 612 |
term "replace" means that the old permission list of the image is abandoned |
| 613 |
(old permission settings are lost). |
| 614 |
|
| 615 |
============================== ====== ======== ====== |
| 616 |
URI Method Image Glance |
| 617 |
============================== ====== ======== ====== |
| 618 |
``/images/<image-id>/members`` PUT ✔ ✔ |
| 619 |
============================== ====== ======== ====== |
| 620 |
|
| 621 |
**image-id** is explained at :ref:`id-ref` |
| 622 |
|
| 623 |
| |
| 624 |
|
| 625 |
==================== ========================= ======== ========= |
| 626 |
Request Header Name Value Image Glance |
| 627 |
==================== ========================= ======== ========= |
| 628 |
X-Auth-Token User authentication token required required |
| 629 |
==================== ========================= ======== ========= |
| 630 |
|
| 631 |
| |
| 632 |
|
| 633 |
Request data should be json-formated. It must consist of a *memberships* field |
| 634 |
which is a list of members with the following fields: |
| 635 |
|
| 636 |
================ ===================== ======== ====== |
| 637 |
Name Description Image Glance |
| 638 |
================ ===================== ======== ====== |
| 639 |
member_id uuid (user id) ✔ ✔ |
| 640 |
can_share Member can share img ignored ✔ |
| 641 |
================ ===================== ======== ====== |
| 642 |
|
| 643 |
**can_share** is optional and ignored in Cyclades/Image. |
| 644 |
|
| 645 |
A request data example:: |
| 646 |
|
| 647 |
{'memberships': [
|
| 648 |
{'member_id': 'uuid-1',
|
| 649 |
'can_share': false}, |
| 650 |
{'member_id': 'uuid-2'},
|
| 651 |
... |
| 652 |
]} |
| 653 |
|
| 654 |
| |
| 655 |
|
| 656 |
=========================== ===================== |
| 657 |
Return Code Description |
| 658 |
=========================== ===================== |
| 659 |
204 (No Content) The request succeeded |
| 660 |
400 (Bad Request) Invalid format for request data |
| 661 |
401 (Unauthorized) Missing or expired user token |
| 662 |
404 (Not Found) Image not found |
| 663 |
405 (Not Allowed) Access to that image is not allowed |
| 664 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 665 |
=========================== ===================== |
| 666 |
|
| 667 |
Add a Member to an Image |
| 668 |
------------------------ |
| 669 |
|
| 670 |
This request appends a user id to the list of users who can access a registered |
| 671 |
image. |
| 672 |
|
| 673 |
===================================== ====== ======== ====== |
| 674 |
URI Method Image Glance |
| 675 |
===================================== ====== ======== ====== |
| 676 |
``/images/<image-id>/members/<uuid>`` PUT ✔ ✔ |
| 677 |
===================================== ====== ======== ====== |
| 678 |
|
| 679 |
**image-id** is explained at :ref:`id-ref` |
| 680 |
|
| 681 |
**uuid** is the unique user id of the user (see `Astakos API |
| 682 |
<astakos-api-guide.html>`_ on how to handle it) |
| 683 |
|
| 684 |
| |
| 685 |
|
| 686 |
==================== ========================= ======== ========= |
| 687 |
Request Header Name Value Image Glance |
| 688 |
==================== ========================= ======== ========= |
| 689 |
X-Auth-Token User authentication token required required |
| 690 |
==================== ========================= ======== ========= |
| 691 |
|
| 692 |
| |
| 693 |
|
| 694 |
=========================== ===================== |
| 695 |
Return Code Description |
| 696 |
=========================== ===================== |
| 697 |
204 (No Content) The request succeeded |
| 698 |
401 (Unauthorized) Missing or expired user token |
| 699 |
404 (Not Found) Image not found |
| 700 |
405 (Not Allowed) Access to that image is not allowed |
| 701 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 702 |
=========================== ===================== |
| 703 |
|
| 704 |
Remove a Member from an Image |
| 705 |
----------------------------- |
| 706 |
|
| 707 |
This request ensures that, after a successful call, the user with the given |
| 708 |
uuid will not have access to that image. |
| 709 |
|
| 710 |
===================================== ====== ======== ====== |
| 711 |
URI Method Image Glance |
| 712 |
===================================== ====== ======== ====== |
| 713 |
``/images/<image-id>/members/<uuid>`` DELETE ✔ ✔ |
| 714 |
===================================== ====== ======== ====== |
| 715 |
|
| 716 |
**image-id** is explained at :ref:`id-ref` |
| 717 |
|
| 718 |
**uuid** is the unique user id of the user (see `Astakos API |
| 719 |
<astakos-api-guide.html>`_ on how to handle it) |
| 720 |
|
| 721 |
| |
| 722 |
|
| 723 |
==================== ========================= ======== ========= |
| 724 |
Request Header Name Value Image Glance |
| 725 |
==================== ========================= ======== ========= |
| 726 |
X-Auth-Token User authentication token required required |
| 727 |
==================== ========================= ======== ========= |
| 728 |
|
| 729 |
| |
| 730 |
|
| 731 |
=========================== ===================== |
| 732 |
Return Code Description |
| 733 |
=========================== ===================== |
| 734 |
204 (No Content) The request succeeded |
| 735 |
401 (Unauthorized) Missing or expired user token |
| 736 |
404 (Not Found) Image not found |
| 737 |
405 (Not Allowed) Access to that image is not allowed |
| 738 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 739 |
=========================== ===================== |
| 740 |
|
| 741 |
List Shared Images |
| 742 |
------------------ |
| 743 |
|
| 744 |
This request returns a list of the images that are shared with a given user. |
| 745 |
|
| 746 |
========================= ====== ======== ====== |
| 747 |
URI Method Image Glance |
| 748 |
========================= ====== ======== ====== |
| 749 |
``/shared-images/<uuid>`` DELETE ✔ ✔ |
| 750 |
========================= ====== ======== ====== |
| 751 |
|
| 752 |
**uuid** is the unique user id of the user (see `Astakos API <astakos-api-guide.html>`_ on how to handle it) |
| 753 |
|
| 754 |
| |
| 755 |
|
| 756 |
==================== ========================= ======== ========= |
| 757 |
Request Header Name Value Image Glance |
| 758 |
==================== ========================= ======== ========= |
| 759 |
X-Auth-Token User authentication token required required |
| 760 |
==================== ========================= ======== ========= |
| 761 |
|
| 762 |
| |
| 763 |
|
| 764 |
=========================== ===================== |
| 765 |
Return Code Description |
| 766 |
=========================== ===================== |
| 767 |
200 (OK) The request succeeded |
| 768 |
401 (Unauthorized) Missing or expired user token |
| 769 |
404 (Not Found) Image not found |
| 770 |
405 (Not Allowed) Access to that image is not allowed |
| 771 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 772 |
=========================== ===================== |
| 773 |
|
| 774 |
In case of a 200 response, the response data is json-formated list of images |
| 775 |
that are shared with given user |
| 776 |
|
| 777 |
================ ===================== ======== ====== |
| 778 |
Name Description Image Glance |
| 779 |
================ ===================== ======== ====== |
| 780 |
image_id The Image ID ✔ ✔ |
| 781 |
can_share Member can share img false ✔ |
| 782 |
================ ===================== ======== ====== |
| 783 |
|
| 784 |
**can_share** in Cyclades/Image is always false and is returned for |
| 785 |
compatibility reasons. |
| 786 |
|
| 787 |
Example Cyclades/Image response:: |
| 788 |
|
| 789 |
{'shared_images': [
|
| 790 |
{'image_id': 'th3-r3qu3573d-1m4g3-1d',
|
| 791 |
'can_share': false}, |
| 792 |
... |
| 793 |
]} |
| 794 |
|
| 795 |
Index of variables |
| 796 |
------------------ |
| 797 |
|
| 798 |
The following variables affect the behavior of many requests. |
| 799 |
|
| 800 |
.. _id-ref: |
| 801 |
|
| 802 |
Image ID |
| 803 |
^^^^^^^^ |
| 804 |
|
| 805 |
The image id is a unique identifier for an image stored in Cyclades/Image or |
| 806 |
Glance. |
| 807 |
|
| 808 |
======================= ======== ====== |
| 809 |
Image-Id Image Glance |
| 810 |
======================= ======== ====== |
| 811 |
Automatically generated ✔ **✘** |
| 812 |
Can be provided by user **✘** ✔ |
| 813 |
======================= ======== ====== |
| 814 |
|
| 815 |
.. _location-ref: |
| 816 |
|
| 817 |
Image File Location at a Pithos Server |
| 818 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 819 |
|
| 820 |
To refer to a pithos location file, use the following format:: |
| 821 |
|
| 822 |
pithos://<unique-user-id>/<container>/<object-path> |
| 823 |
|
| 824 |
The terms unique-user-id (uuid), container and object-path are used as defined |
| 825 |
in `Pithos <pithos.html>`_ context. |
| 826 |
|
| 827 |
.. _container-format-ref: |
| 828 |
|
| 829 |
Container format |
| 830 |
^^^^^^^^^^^^^^^^ |
| 831 |
|
| 832 |
===== ================================= ======== ====== |
| 833 |
Value Description Image Glance |
| 834 |
===== ================================= ======== ====== |
| 835 |
aki Amazon kernel image ✔ ✔ |
| 836 |
ari Amazon ramdisk image ✔ ✔ |
| 837 |
ami Amazon machine image ✔ ✔ |
| 838 |
bare no container or metadata envelope default default |
| 839 |
ovf Open Virtualization Format ✔ ✔ |
| 840 |
===== ================================= ======== ====== |
| 841 |
|
| 842 |
.. _disk-format-ref: |
| 843 |
|
| 844 |
Disk format |
| 845 |
^^^^^^^^^^^ |
| 846 |
|
| 847 |
======== ================================= ======== ====== |
| 848 |
Value Description Image Glance |
| 849 |
======== ================================= ======== ====== |
| 850 |
diskdump Any disk image dump default **✘** |
| 851 |
extdump EXT3 image ✔ **✘** |
| 852 |
ntfsdump NTFS image ✔ **✘** |
| 853 |
raw Unstructured disk image **✘** ✔ |
| 854 |
vhd (VMWare,Xen,MS,VirtualBox, a.o.) **✘** ✔ |
| 855 |
vmdk Another common disk format **✘** ✔ |
| 856 |
vdi (VirtualBox, QEMU) **✘** ✔ |
| 857 |
iso optical disc (e.g. CDROM) **✘** ✔ |
| 858 |
qcow2 (QEMU) **✘** ✔ |
| 859 |
aki Amazon kernel image **✘** ✔ |
| 860 |
ari Amazon ramdisk image **✘** ✔ |
| 861 |
ami Amazon machine image **✘** ✔ |
| 862 |
======== ================================= ======== ====== |
| 863 |
|
| 864 |
.. _store-ref: |
| 865 |
|
| 866 |
Store types |
| 867 |
^^^^^^^^^^^ |
| 868 |
|
| 869 |
======================= ======== ====== |
| 870 |
X-Image-Meta-Store Image Glance |
| 871 |
======================= ======== ====== |
| 872 |
pithos ✔ **✘** |
| 873 |
file **✘** ✔ |
| 874 |
s3 **✘** ✔ |
| 875 |
swift **✘** ✔ |
| 876 |
======================= ======== ====== |