2
Copyright 2010 OpenStack, LLC
5
Licensed under the Apache License, Version 2.0 (the "License"); you may
6
not use this file except in compliance with the License. You may obtain
7
a copy of the License at
9
http://www.apache.org/licenses/LICENSE-2.0
11
Unless required by applicable law or agreed to in writing, software
12
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
License for the specific language governing permissions and limitations
20
Image metadata made available through Glance can be stored in image
21
`registries`. Image registries are any web service that adheres to the
22
Glance REST-like API for image metadata.
24
Glance comes with a server program ``glance-registry`` that acts
25
as a reference implementation of a Glance Registry.
27
Please see the document :doc:`on Controlling Servers <controllingservers>`
28
for more information on starting up the Glance registry server that ships
34
Any web service that publishes an API that conforms to the following
35
REST-like API specification can be used by Glance as a registry.
40
The following is a brief description of the Glance API::
42
GET /images Return brief information about public images
43
GET /images/detail Return detailed information about public images
44
GET /images/<ID> Return metadata about an image in HTTP headers
45
POST /images Register metadata about a new image
46
PUT /images/<ID> Update metadata about an existing image
47
DELETE /images/<ID> Remove an image's metadata from the registry
49
Filtering Images Returned via ``GET /images`` and ``GET /images/detail``
50
------------------------------------------------------------------------
52
Both the ``GET /images`` and ``GET /images/detail`` requests take query
53
parameters that serve to filter the returned list of images. The following
54
list details these query parameters.
58
Filters images having a ``name`` attribute matching ``NAME``.
60
* ``container_format=FORMAT``
62
Filters images having a ``container_format`` attribute matching ``FORMAT``
64
For more information, see :doc:`About Disk and Container Formats <formats>`
66
* ``disk_format=FORMAT``
68
Filters images having a ``disk_format`` attribute matching ``FORMAT``
70
For more information, see :doc:`About Disk and Container Formats <formats>`
74
Filters images having a ``status`` attribute matching ``STATUS``
76
For more information, see :doc:`About Image Statuses <statuses>`
80
Filters images having a ``size`` attribute greater than or equal to ``BYTES``
84
Filters images having a ``size`` attribute less than or equal to ``BYTES``
86
These two resources also accept sort parameters:
90
Results will be ordered by the specified image attribute ``KEY``. Accepted
91
values include ``id``, ``name``, ``status``, ``disk_format``,
92
``container_format``, ``size``, ``created_at`` (default) and ``updated_at``.
96
Results will be sorted in the direction ``DIR``. Accepted values are ``asc``
97
for ascending or ``desc`` (default) for descending.
103
The body of the request will be a JSON-encoded set of data about
104
the image to add to the registry. It will be in the following format::
110
'disk_format': <DISK_FORMAT>,
111
'container_format': <CONTAINER_FORMAT>,
112
'properties': [ ... ]
116
The request shall validate the following conditions and return a
117
``400 Bad request`` when any of the conditions are not met:
119
* ``status`` must be non-empty, and must be one of **active**, **saving**,
120
**queued**, or **killed**
122
* ``disk_format`` must be non-empty, and must be one of **ari**, **aki**,
123
**ami**, **raw**, **iso**, **vhd**, **vdi**, **qcow2**, or **vmdk**
125
* ``container_format`` must be non-empty, and must be on of **ari**,
126
**aki**, **ami**, **bare**, or **ovf**
128
* If ``disk_format`` *or* ``container_format`` is **ari**, **aki**,
129
**ami**, then *both* ``disk_format`` and ``container_format`` must be
132
* ``id`` must be a uuid in hexadecimal string notation
133
(i.e. '71c675ab-d94f-49cd-a114-e12490b328d9')
138
.. todo:: Complete examples for Glance registry API
added
removed
doc/source/registries.rst
