Jump to: navigation, search


  • Launchpad Entry: NovaSpec:osapi-image-filtering
  • Created: May 26, 2011
  • Contributors: AlexMeade


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.


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.


Glance supports adding filtering parameters to queries on the /images and /images/detail resources.


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:


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:



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.