Launchpad Entry: https://blueprints.launchpad.net/glance/+spec/api-results-filtering
Created: April 13, 2011
Contributors: GlenCampbell
Summary
The current Glance implementation is somewhat simplistic, especially for a multi-tenanted environment. This specification is for a proposal to enhance the Glance REST API by allowing query parameters on the /images and /images/detail resources.
Release Note
The Glance API is extended with support for query parameters that allow the user to alter the set of images returned.
Rationale
In a multi-tenanted environment, especially one with thousands of users or customers, returning a collection of images can be extremely cumbersome. By providing filtering via query string parameters, this collection can be used to reduce the set of images to a more manageable size.
User stories
As a customer who needs to restore a server to a backup, I need a list of all of the non-public images created from this specific server.
As a customer who wants to rebuild a server, I need a list of base images (public) and my company-tagged images.
As a service provider with specific requirements for images, I need a list of only those images that are a) public, and b) are tagged with the metadata that I specify.
As a user with OS images that require a minimum amount of RAM, I want to only show images that meet my RAM requirements.
Assumptions
Design
There are two sets of parameters for Glance images: those that are core values (required for each image, and known to the code) and user-defined. Core values are stored with the image and can be queried with API query strings. User-defined values are set via x-image-meta-* HTTP headers, and they are queried (via a GET request) using the same headers.
Core Parameters
The following core query parameters are supported:
Parameter |
Example |
disk_format |
?disk_format=NN |
container_format |
?container_format=NN |
name |
?name=XXX |
status |
?status=XXX |
size_min |
?size_min=NNN |
size_max |
?size_max=NNN |
The default behavior of /images should not change (i.e., it still returns only public images).
User-defined Parameters
To retrieve images based on other metadata parameters use the query string ?property-{name} , where {name} is the value user for the x-image-meta-property-* header. For example, if the image was stored with a header like this:
x-image-meta-property-rax-managed: Yes
Then that image could be retrieved with this query:
/images?property-rax-managed=Yes
Implementation
This section should describe a plan of action (the "how") to implement the changes discussed. Could include subsections like:
UI Changes
Should cover changes required to the UI, or specific UI that is required to implement this
Code Changes
Code changes should include an overview of what needs to change, and in some cases even the specific details.
Migration
Include:
- data migration, if any
- redirects from old URLs to new ones, if any
- how users will be pointed to the new way of doing things, if necessary.
Test/Demo Plan
This need not be added or completed until the specification is nearing beta.
Unresolved issues
This should highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved.
BoF agenda and discussion
Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarising what was discussed and note any options that were rejected.