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