Support to query nova resources filter by changes-before

The compute API already has the changes-since filter to filter servers updated since the given time and this spec proposes to add a changes-before filter to filter servers updated before the given time. In addition, the filters could be used in conjunction to build a kind of time range filter, e.g. to get the nova resources between changes-since and changes-before.

Problem description

By default, nova can query the instance resource in the updated_at >= changes-since time period. Users can only query resources operated at given time, not during given period. Users may be interested in resources operated in a specific period for monitoring or statistics purpose but currently they have to retrieve and filter the resources by themselves. This change can bring facility to users and also improve the efficiency of timestamp based query.

Use Cases

In large scale environment, lots of resources were created in system. For tracing the change of resource, user or manage system only need to get those resources which was changed with some time period, instead of querying all resources every time to see which was changed.

For example, if you are trying to get the nova resources that were changed before ‘2018-07-26T10:31:49Z’, you can filter servers like:

  • GET /servers/detail?changes-before=2018-07-26T10:31:49Z

Or if you want to filter servers in the time range(e.g. changes-since= 2018-07-26T10:31:49Z -> changes-before=2018-07-30T10:31:49Z), you can filter servers like:

  • GET /servers/detail?changes-since=2018-07-26T10:31:49Z&changes-before= 2018-07-30T10:31:49Z

Proposed change

Add a new microversion to os-instance-actions, os-migrations and servers list APIs to support changes-before.

Introduce a new changes-before filter for retrieving resources. It accepts a timestamp and projects will return resources whose updated_at fields are earlier than this timestamp, it means that “updated_at <= changes-before”. Its(changes-before) value is optional. If changes-since and changes-before pass the value, the projects will return resources whose updated_at fields are earlier than or equal to this changes-before, and later than or equal to changes-since.

Reading deleted resources

Like the changes-since filter, the changes-before filter will also return deleted servers.

This spec does not propose to change any read-deleted behavior in the os-instance-actions or os-migrations APIs. The os-instance-actions API with the 2.21 microversion allows retrieving instance actions for a deleted server resource. The os-migrations API takes an optional instance_uuid filter parameter but does not support returning deleted migration records like changes-since does in the servers API.


As discussed in Problem description section, users can retrieve and then filter resources by themselves, but this method is extremely inconvenient. Having said that, services like Searchlight do exist which have similar functionality, i.e. listening for nova notifications and storing them in a time-series database like elasticsearch from which results can later be queried. However, requiring Searchlight or a similar alternative solution for this relatively small change is likely excessive. Leaving filtering work to the database can utilize the optimization of database engine and also reduce data transmitted from server to client.

Data model impact


REST API impact

A new microversion will be added.

List API will accept new query string parameter changes-before. Judging in the following cases:

  • If the user specifies the changes-before < changes-since, it will return HTTPBadRequest 400.

  • If the user only specifies changes-before, all nova resource before changes-before will be returned, including the deleted servers.

  • If the user specifies changes-since and changes-before, that will get changes from a specific period, including the deleted servers.

  • When the user only specifies changes-since, the original features remain unchanged.

Users can pass time to the list API url to retrieve resources operated since a specific time.

  • GET /servers?changes-before=2018-07-26T10:31:49Z

  • GET /servers/detail?changes-before=2018-07-26T10:31:49Z

  • GET /servers/{server_id}/os-instance-actions?changes-before= 2018-07-26T10:31:49Z

  • GET /os-migrations?changes-before=2018-07-26T10:31:49Z

Security impact


Notifications impact


Other end user impact

Python client may add help to inform users this new filter. Add support for the changes-before filter in python-novaclient for the ‘nova list’, ‘nova migration-list’ and ‘nova instance-action-list’ command.

Performance Impact


Other deployer impact


Developer impact


Upgrade impact




Primary assignee:

Brin Zhang

Work Items

  • Add querying support in sql

  • Add API filter

  • Add related test

  • Add support for changes-before to the ‘nova list’ operation in novaclient

  • Add support for changes-before to the ‘nova instance-action-list’ in novaclient

  • Add support for changes-before to the ‘nova migration-list’ in novaclient




  • Add related unittest

  • Add related functional test

Documentation Impact

The nova API documentation will need to be updated to reflect the REST API changes, and adding microversion instructions.





Release Name