ceab6b3ed4
This just changes the value of image.id, leaving the key name alone. We also enforce image ids provided on an image create be a uuid. Implements blueprint uuid-image-identifiers Change-Id: I22ba69550ccbc04a24d680748d60414d2d0f1a99
139 lines
4.5 KiB
ReStructuredText
139 lines
4.5 KiB
ReStructuredText
..
|
|
Copyright 2010 OpenStack, LLC
|
|
All Rights Reserved.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
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 :doc:`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 :doc:`About Disk and Container Formats <formats>`
|
|
|
|
* ``disk_format=FORMAT``
|
|
|
|
Filters images having a ``disk_format`` attribute matching ``FORMAT``
|
|
|
|
For more information, see :doc:`About Disk and Container Formats <formats>`
|
|
|
|
* ``status=STATUS``
|
|
|
|
Filters images having a ``status`` attribute matching ``STATUS``
|
|
|
|
For more information, see :doc:`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
|
|
********
|
|
|
|
.. todo:: Complete examples for Glance registry API
|