Nova/ImageFilterSpec
- Launchpad Entry: NovaSpec:osapi-image-filtering
- Created: May 26, 2011
- Contributors: AlexMeade
Contents
Summary
The Glance REST API has recently implemented the ability to add query parameters on the /images and /images/detail resources. This specification is for a proposal to expose those changes through the Nova REST API.
Release Note
The Nova API is extended with support for query parameters that allow the user to filter the set of images returned when using the Glance image service.
Rationale
Returning a large collection of images can make it difficult to effectively utilize the information. Allowing the filtering of these results could allow users to narrow down the results returned so that they are easily manageable.
User stories
As a service provider with specific image requirements, I only need to list images with certain metadata.
As a customer who wants to rebuild a server, I need to locate an image with a specific name.
Assumptions
Glance supports adding filtering parameters to queries on the /images and /images/detail resources.
Design
There are two types of Glance image parameters: core parameters that describe every image and user-defined.
Core Parameters
Core parameters are values that are stored with the image and can be queried with an API query string.
The following core query parameters are supported:
| Parameter |
| name |
| status |
User-defined Parameters
User-defined values are set via x-image-meta-* HTTP headers, and they are queried (via a GET request) using the same headers.
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
Code Changes
Update nova/images to allow filter parameters Minor additions to tests
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.
