Statistics
| Branch: | Tag: | Revision:

root / docs / plankton-api-guide.rst @ bd4bb8ae

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 VM 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
======================= ========  ======