Cyclades/Image API Guide

Introduction

The Image Service of Synnefo is implemented as part of Cyclades. It exposes the OpenStack Glance API, with minor changes or additions wherever needed.

This document’s goals are:

  • Define the Cyclades/Image ReST API
  • Clarify the differences between Cyclades/Image and Glance

Image ReST API

Description URI Method Image Glance
List Available Images /images GET
List Available Images in Detail /images/detail GET
Add or update an Image /images POST
Update an Image /images PUT
/images/<img-id> PUT
Retrieve Image Metadata /images/<img-id> HEAD
Retrieve Raw Image Data /images/<img-id> GET
List Image Memberships /images/<img-id>/members GET
Replace a Membership List /images/<img-id>/members PUT
Add a Member to an Image /images/<img-id>/members/<member> PUT
Remove a Member from an Image /images/<img-id>/members/<member> DELETE
List Shared Images /shared-images/<member> GET

Authentication

Image 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. Image handles the communication with Astakos to verify the token validity and obtain identity credentials.

Glance handles authentication in a similar manner, with the only difference being the suggested identity manager.

Image Metadata Format

In Cyclades Image API all image metadata are viewed as HTTP headers that are starting with the x-image-meta- prefix. All metadata must be encoded with the UTF-8 encoding. Since the image metadata must be valid HTTP headers, user defined metadata like the image’s name or properties must also be properly quoted. Finally, image properties that are viewed as HTTP headers and are starting with the x-image-meta-property- prefix, are not case-sensitive and all punctuation characters will be replaced with underscore.

List Available Images

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:

  • registered by the user
  • shared to user by others
  • public
URI Method Image Glance
/images GET

Request Parameter Name Value Image Glance
name Return images of given name
container_format Return images of given container format
disk_format Return images of given disk format
status Return images of given status
size_min Return images of size >= to given value
size_max Return images of size >= to given value
sort_key Sort images against given key
sort_dir Sort images in given direction

container_format values are listed at Container format

disk_format values are listed at Disk format

sort_key values: id, name, status, size, disk_format, container_format, created_at, updated_at

sort_dir Description Image Glance
asc Ascending order default default
desc Descending order

Request Header Name Value Image Glance
X-Auth-Token User authentication token required required

Return Code Description
200 (OK) The request succeeded
400 (Bad Request) Raised in case of invalid values for
sort_key, sort_dir, size_max or size_min
401 (Unauthorized) Missing or expired user token
500 (Internal Server Error) The request cannot be completed because of an internal error

The response data is a list of images in a json format containing the fields presented bellow

Name Description Image Glance
id A unique image id
uri Unique id in URI form
name The name of the image
status The VM status
disk_format The disc format
container_format The container format
size Image size in bytes

Example Image response:

[{
    "status": "available",
    "name": "ubuntu",
    "disk_format": "diskdump",
    "container_format": "bare",
    "id": "5583ffe1-5273-4c84-9e32-2fbe476bd7b7",
    "size": 2622562304
}, {
    "status": "available",
    "name": "Ubuntu-10.04",
    "disk_format": "diskdump",
    "container_format": "bare",
    "id": "907ef618-c03a-4473-9914-9348e12890c1",
    "size": 761368576
}]

List Available Images in Detail

This request returns the same list of images as in List Available Images, but the results are reacher in metadata.

URI Method Image Glance
/images/detail GET

Request parameters and headers as well as response headers and error codes are exactly the same as in List Available Images, both syntactically and semantically.

The response data is a list of images in json format containing the fields presented bellow

Name Description Image Glance
id A unique image id
uri Unique id in URI form
location Pithos file location
name The name of the image
status The Image status
disk_format The disc format
container_format The container format
size Image size in bytes
checksum file MD5 checksum
created_at Timestamp of creation
updated_at Timestamp of update
deleted_at Timestamp of deletion
is_public True if img is public
min_ram Minimum ram required
min_disk Maximum ram required
owner Image owner
properties Custom properties

Example Image response:

[{
    "status": "available",
    "location": "pithos://u53r-1d/images/my/path/example_image_build.diskdump"
    "name": "ubuntu",
    "disk_format": "diskdump",
    "container_format": "bare",
    "created_at": "2013-03-29 14:14:34",
    "deleted_at": "",
    "id": "5583ffe1-5273-4c84-9e32-2fbe476bd7b7",
    "size": 2622562304,
    "is_public": "True",
    "checksum": "a387aaaae583bc65daacf12d6be502bd7cfbbb254dcd452f92ca31f4c06a9208",
    "properties": {
        "partition_table": "msdos",
        "kernel": "3.8.3",
        "osfamily": "linux",
        "users": "root user",
        "gui": "GNOME 3.4.2",
        "sortorder": "5",
        "os": "fedora",
        "root_partition": "1",
        "description": "Fedora release 17 (Beefy Miracle)"}
}, {
    "location": "pithos://0th3r-u53r-1d/images/ubuntu_10_04.diskdump"
    "status": "available",
    "name": "Ubuntu-10.04",
    "disk_format": "diskdump",
    "container_format": "bare",
    "id": "907ef618-c03a-4473-9914-9348e12890c1",
    "size": 761368576
    "created_at": "2013-03-29 14:14:34",
    "deleted_at": ""
}]

Add or update an image

According to the Synnefo approach, this request performs two operations:

  • registers a new image to Cyclades/Image
  • commits metadata for the new image
  • update the metadata of an existing image

The physical image file must be uploaded on a Pithos 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).

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.

URI Method Image Glance
/images POST

Request Header Name Value Image Glance
X-Auth-Token User authentication token required required
X-Image-Meta-Name Img name required required
X-Image-Meta-Id Unique image id
X-Image-Meta-Location img file location @Pithos required
X-Image-Meta-Store Storage system
X-Image-Meta-Disk-Format Img disk format
X-Image-Meta-Disk_format Img disk format
X-Image-Meta-Container-Format Container format
X-Image-Meta-Container_format Container format
X-Image-Meta-Size Size of img file
X-Image-Meta-Checksum MD5 checksum of img file
X-Image-Meta-Is-Public Make image public
X-Image-Meta-Is_public Make image public
x-image-meta-Min-Ram Minimum ram required (MB)
x-image-meta-Min-Disk Maximum ram required (MB)
X-Image-Meta-Owner Image owner
X-Image-Meta-Property-* Property prefix

X-Meta-Location format is described at Image File Location at a Pithos Server

X-Image-Meta-Id is explained at Image ID

X-Image-Meta-Store values are listed at Store types

X-Image-Meta-Disk-Format values are listed at Disk format

X-Image-Meta-Container-Format values are listed at Container format

X-Image-Meta-Size is optional, but should match the actual image file size.

X-Image-Meta-Is-Public values are true or false (case insensitive)

X-Image-Meta-Property-* is used as a prefix to set custom, free-form key:value properties on an image, e.g.:

X-Image-Meta-Property-OS: Debian Linux
X-Image-Meta-Property-Users: Root

Return Code Description
200 (OK) The request succeeded
400 (Bad Request)  
No name header
Illegal header value
Invalid size or checksum
401 (Unauthorized) Missing or expired user token
404 (Not Found) File not found on given location
500 (Internal Server Error) The request cannot be completed because of an internal error
501 (Not Implemented) Location header is empty or omitted

The following is used when the response code is 200:

Response Header Description Image Glance
X-Image-Meta-Id Unique img id
X-Image-Meta-Name Img name
X-Image-Meta-Disk-Format Disk format
X-Image-Meta-Container-Format Container format
X-Image-Meta-Size Img file size
X-Image-Meta-Checksum Img file MD5 checksum
X-Image-Meta-Location Pithos file location
X-Image-Meta-Created-At Date of img creation
X-Image-Meta-Deleted-At Date of img deletion
X-Image-Meta-Status Img status
X-Image-Meta-Is-Public True if img is public
X-Image-Meta-Owner Img owner or tentant
X-Image-Meta-Property-* Custom img properties

Update an Image

In Cyclades/Image, an image can be updated either by re-registering with different metadata, or by using the request described in the present subsection.

In Glance, an update is implemented as a PUT request on /images URI. The method described bellow is not part of the Glance API.

URI Method Image Glance
/images PUT
/images/<image-id> PUT

The following refers only to the Cyclades/Image implementation.

image-id is explained at Image ID


Request Header Name Value
X-Auth-Token User authentication token
X-Image-Meta-Name New image name
X-Image-Meta-Disk-Format New disk format
X-Image-Meta-Container-Format New container format
X-Image-Meta-Status New image status
X-Image-Meta-Is-Public (un)publish the image
X-Image-Meta-Owner Set an owner
X-Image-Meta-Property-* Add / modify properties

X-Image-Meta-Disk-Format values are listed at Disk format

X-Image-Meta-Container-Format values are listed at Container format

X-Image-Meta-Size is optional, but should much the actual image file size.

X-Image-Meta-Is-Public values are true or false (case insensitive)

X-Image-Meta-Property-* is used as a prefix to update image property values, or set some extra properties. If a registered image already contains some custom properties that are not addressed in the update request, these properties will remain untouched. For example:

X-Image-Meta-Property-OS: Debian Linux
X-Image-Meta-Property-Users: Root

Return Code Description
200 (OK) The request succeeded
400 (Bad Request)  
Illegal header value
Invalid size or checksum
401 (Unauthorized) Missing or expired user token
404 (Not found) Image not found
405 (Not allowed) Current user does not have permission to change the image
500 (Internal Server Error) The request cannot be completed because of an internal error

The following is received when the response code is 200:

Response Header Description
X-Image-Meta-Id Unique img id
X-Image-Meta-Name Img name
X-Image-Meta-Disk-Format Disk format
X-Image-Meta-Container-Format Container format
X-Image-Meta-Size Img file size
X-Image-Meta-Checksum Img file MD5 checksum
X-Image-Meta-Location Pithos file location
X-Image-Meta-Created-At Date of img creation
X-Image-Meta-Deleted-At Date of img deletion
X-Image-Meta-Status Img status
X-Image-Meta-Is-Public True if img is public
X-Image-Meta-Owner Img owner or tentant
X-Image-Meta-Property-* Custom img properties

Hint

In Cyclades/Image, use POST to completely reset all image properties and metadata, but use PUT to update a few values without affecting the rest.

Retrieve Image Metadata

This request returns the metadata of an image. Images are identified by their unique image id.

In a typical scenario, client applications would query the server to List Available Images for them and then choose one of the image ids returned.

URI Method Image Glance
/images/<image-id> HEAD

image-id is explained at Image ID


Request Header Name Value Image Glance
X-Auth-Token User authentication token required required

Return Code Description
200 (OK) The request succeeded
401 (Unauthorized) Missing or expired user token
404 (Not Found) Image not found
405 (Not Allowed) Access to that image is not allowed
500 (Internal Server Error) The request cannot be completed because of an internal error

Response Header Description Image Glance
X-Image-Meta-Id Unique img id
X-Image-Meta-Location Pithos file location
X-Image-Meta-URI URI of image file
X-Image-Meta-Name Img name
X-Image-Meta-Disk-Format Disk format
X-Image-Meta-Disk_format Disk format
X-Image-Meta-Container-Format Container format
X-Image-Meta-Container_format Container format
X-Image-Meta-Size Img file size
X-Image-Meta-Checksum Img file MD5 checksum
X-Image-Meta-Created-At Date of img creation
X-Image-Meta-Created_At Date of img creation
X-Image-Meta-Updated-At Last modification
X-Image-Meta-Updated_At Last modification
X-Image-Meta-Deleted-At Date of img deletion
X-Image-Meta-Deleted_At Date of img deletion
X-Image-Meta-Status Img status
X-Image-Meta-Is-Public True if img is public
X-Image-Meta-Min-Ram Minimum image RAM
X-Image-Meta-Min-Disk Minimum disk size
X-Image-Meta-Owner Img owner or tentant
X-Image-Meta-Property-* Custom img properties

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).

X-Image-Meta-Store values are listed at Store types

X-Image-Meta-Disk-Format values are listed at Disk format

X-Image-Meta-Container-Format values are listed at Container format

X-Image-Meta-Is-Public values are true or false (case insensitive)

X-Image-Meta-Property-* is used as a prefix to set custom, free-form key:value properties on an image, e.g.:

X-Image-Meta-Property-OS: Debian Linux
X-Image-Meta-Property-Users: Root

Example Cyclades/Image Headers response:

x-image-meta-id: 940509eb-eb4f-496c-8443-22ffd24912e9
x-image-meta-location: pithos://25cced7-bd53-4145-91ee-cf4737e9fb2/images/some-image.diskdump
x-image-meta-name: Debian Desktop
x-image-meta-disk-format: diskdump
x-image-meta-container-format: bare
x-image-meta-size: 3399127040
x-image-meta-checksum: d0f28e4d72927c90eadf30917d94d0156781fe1351ed16402b538316d404
x-image-meta-created-at: 2013-02-26 12:04:31
x-image-meta-updated-at: 2013-02-26 12:05:28
x-image-meta-deleted-at:
x-image-meta-status: available
x-image-meta-is-public: True
x-image-meta-owner: 25cced7-bd53-4145-91ee-cf4737e9fb2
x-image-meta-property-partition-table: msdos
x-image-meta-property-osfamily: linux
x-image-meta-property-sortorder: 2
x-image-meta-property-description: Debian 6.0.7 (Squeeze) Desktop
x-image-meta-property-os: debian
x-image-meta-property-users: root user
x-image-meta-property-kernel: 2.6.32
x-image-meta-property-root-partition: 1
x-image-meta-property-gui: GNOME 2.30.2

Retrieve Raw Image Data

In Image, the raw image data is stored at a Pithos server and it can be downloaded from the Pithos web UI, with a client or with kamaki. The location of an image file can be retrieved from the X-Image-Meta-Location header field (see Retrieve Image Meta)

In Glance, the raw image can be downloaded with a GET request on /images/<image-id>.

List Image Memberships

This request returns the list of users who can access an image. Cyclades/Image returns an empty list if the image is publicly accessible.

URI Method Image Glance
/images/<image-id>/members GET

image-id is explained at Image ID


Request Header Name Value Image Glance
X-Auth-Token User authentication token required required

Return Code Description
200 (OK) The request succeeded
401 (Unauthorized) Missing or expired user token
404 (Not Found) Image not found
405 (Not Allowed) Access to that image is not allowed
500 (Internal Server Error) The request cannot be completed because of an internal error

The response data is a list of users (members) who can access this image

Name Description Image Glance
member_id uuid (user id)
can_share Member can share img false

can_share in Cyclades/Image is always false and is returned for compatibility reasons.

Example Cyclades/Image response:

{'members': [
    {'member_id': 'th15-4-u53r-1d-fr0m-p1th05',
    'can_share': false},
    ...
]}

Replace a Membership List

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).

URI Method Image Glance
/images/<image-id>/members PUT

image-id is explained at Image ID


Request Header Name Value Image Glance
X-Auth-Token User authentication token required required

Request data should be json-formated. It must consist of a memberships field which is a list of members with the following fields:

Name Description Image Glance
member_id uuid (user id)
can_share Member can share img ignored

can_share is optional and ignored in Cyclades/Image.

A request data example:

{'memberships': [
    {'member_id': 'uuid-1',
    'can_share': false},
    {'member_id': 'uuid-2'},
    ...
]}

Return Code Description
204 (No Content) The request succeeded
400 (Bad Request) Invalid format for request data
401 (Unauthorized) Missing or expired user token
404 (Not Found) Image not found
405 (Not Allowed) Access to that image is not allowed
500 (Internal Server Error) The request cannot be completed because of an internal error

Add a Member to an Image

This request appends a user id to the list of users who can access a registered image.

URI Method Image Glance
/images/<image-id>/members/<uuid> PUT

image-id is explained at Image ID

uuid is the unique user id of the user (see Astakos API on how to handle it)


Request Header Name Value Image Glance
X-Auth-Token User authentication token required required

Return Code Description
204 (No Content) The request succeeded
401 (Unauthorized) Missing or expired user token
404 (Not Found) Image not found
405 (Not Allowed) Access to that image is not allowed
500 (Internal Server Error) The request cannot be completed because of an internal error

Remove a Member from an Image

This request ensures that, after a successful call, the user with the given uuid will not have access to that image.

URI Method Image Glance
/images/<image-id>/members/<uuid> DELETE

image-id is explained at Image ID

uuid is the unique user id of the user (see Astakos API on how to handle it)


Request Header Name Value Image Glance
X-Auth-Token User authentication token required required

Return Code Description
204 (No Content) The request succeeded
401 (Unauthorized) Missing or expired user token
404 (Not Found) Image not found
405 (Not Allowed) Access to that image is not allowed
500 (Internal Server Error) The request cannot be completed because of an internal error

List Shared Images

This request returns a list of the images that are shared with a given user.

URI Method Image Glance
/shared-images/<uuid> DELETE

uuid is the unique user id of the user (see Astakos API on how to handle it)


Request Header Name Value Image Glance
X-Auth-Token User authentication token required required

Return Code Description
200 (OK) The request succeeded
401 (Unauthorized) Missing or expired user token
404 (Not Found) Image not found
405 (Not Allowed) Access to that image is not allowed
500 (Internal Server Error) The request cannot be completed because of an internal error

In case of a 200 response, the response data is json-formated list of images that are shared with given user

Name Description Image Glance
image_id The Image ID
can_share Member can share img false

can_share in Cyclades/Image is always false and is returned for compatibility reasons.

Example Cyclades/Image response:

{'shared_images': [
    {'image_id': 'th3-r3qu3573d-1m4g3-1d',
    'can_share': false},
    ...
]}

Index of variables

The following variables affect the behavior of many requests.

Image ID

The image id is a unique identifier for an image stored in Cyclades/Image or Glance.

Image-Id Image Glance
Automatically generated
Can be provided by user

Image File Location at a Pithos Server

To refer to a pithos location file, use the following format:

pithos://<unique-user-id>/<container>/<object-path>

The terms unique-user-id (uuid), container and object-path are used as defined in Pithos context.

Container format

Value Description Image Glance
aki Amazon kernel image
ari Amazon ramdisk image
ami Amazon machine image
bare no container or metadata envelope default default
ovf Open Virtualization Format

Disk format

Value Description Image Glance
diskdump Any disk image dump default
extdump EXT3 image
ntfsdump NTFS image
raw Unstructured disk image
vhd (VMWare,Xen,MS,VirtualBox, a.o.)
vmdk Another common disk format
vdi (VirtualBox, QEMU)
iso optical disc (e.g. CDROM)
qcow2 (QEMU)
aki Amazon kernel image
ari Amazon ramdisk image
ami Amazon machine image

Store types

X-Image-Meta-Store Image Glance
pithos
file
s3
swift