glance/doc/source/registries.rst

Image Registries

Image metadata made available through Glance can be stored in image registries. Image registries are any web service that adheres to the Glance REST-like API for image metadata.

Glance comes with a server program glance-registry that acts as a reference implementation of a Glance Registry.

Please see the document on Controlling Servers <controllingservers> for more information on starting up the Glance registry server that ships with Glance.

Glance Registry API

Any web service that publishes an API that conforms to the following REST-like API specification can be used by Glance as a registry.

API in Summary

The following is a brief description of the Glance API:

GET     /images         Return brief information about public images
GET     /images/detail  Return detailed information about public images
GET     /images/<ID>    Return metadata about an image in HTTP headers
POST    /images         Register metadata about a new image
PUT     /images/<ID>    Update metadata about an existing image
DELETE  /images/<ID>    Remove an image's metadata from the registry

Filtering Images Returned via GET /images and GET /images/detail

Both the GET /images and GET /images/detail requests take query parameters that serve to filter the returned list of images. The following list details these query parameters.

• name=NAME

  Filters images having a name attribute matching NAME.

• container_format=FORMAT

  Filters images having a container_format attribute matching FORMAT

  For more information, see About Disk and Container Formats <formats>

• disk_format=FORMAT

  Filters images having a disk_format attribute matching FORMAT

  For more information, see About Disk and Container Formats <formats>

• status=STATUS

  Filters images having a status attribute matching STATUS

  For more information, see About Image Statuses <statuses>

• size_min=BYTES

  Filters images having a size attribute greater than or equal to BYTES

• size_max=BYTES

  Filters images having a size attribute less than or equal to BYTES

These two resources also accept sort parameters:

• sort_key=KEY

  Results will be ordered by the specified image attribute KEY. Accepted values include id, name, status, disk_format, container_format, size, created_at (default) and updated_at.

• sort_dir=DIR

  Results will be sorted in the direction DIR. Accepted values are asc for ascending or desc (default) for descending.

POST /images

The body of the request will be a JSON-encoded set of data about the image to add to the registry. It will be in the following format:

{'image':
  {'id': <ID>|None,
   'name': <NAME>,
   'status': <STATUS>,
   'disk_format': <DISK_FORMAT>,
   'container_format': <CONTAINER_FORMAT>,
   'properties': [ ... ]
  }
}

The request shall validate the following conditions and return a 400 Bad request when any of the conditions are not met:

• status must be non-empty, and must be one of active, saving, queued, or killed
• disk_format must be non-empty, and must be one of ari, aki, ami, raw, iso, vhd, vdi, qcow2, or vmdk
• container_format must be non-empty, and must be on of ari, aki, ami, bare, or ovf
• If disk_format or container_format is ari, aki, ami, then both disk_format and container_format must be the same.
• id must be a uuid in hexadecimal string notation (i.e. '71c675ab-d94f-49cd-a114-e12490b328d9')

Examples

Complete examples for Glance registry API