Resource retrieving: add changes-before filter
Introduce a new changes-before filter for retrieving resources. It accepts a timestamp and projects will return resources that updated_at field is earlier than this timestamp. APIImpact bp:support-to-query-nova-resources-filter-by-changes-before Change-Id: I50fb6e16f1be8be5bcfc11009a0099d9e43e9da0
This commit is contained in:
parent
732075880e
commit
ead00db79c
|
@ -0,0 +1,189 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
========================================================
|
||||
Support to query nova resources filter by changes-before
|
||||
========================================================
|
||||
|
||||
https://blueprints.launchpad.net/nova/+spec/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.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
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
|
||||
-----------------
|
||||
None
|
||||
|
||||
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
|
||||
---------------
|
||||
None
|
||||
|
||||
Notifications impact
|
||||
--------------------
|
||||
None
|
||||
|
||||
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
|
||||
------------------
|
||||
None
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
None
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
None
|
||||
|
||||
Upgrade impact
|
||||
--------------
|
||||
None
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
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
|
||||
|
||||
Dependencies
|
||||
============
|
||||
None
|
||||
|
||||
Testing
|
||||
=======
|
||||
* 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.
|
||||
|
||||
References
|
||||
==========
|
||||
None
|
||||
|
||||
History
|
||||
=======
|
||||
.. list-table:: Revisions
|
||||
:header-rows: 1
|
||||
|
||||
* - Release Name
|
||||
- Description
|
||||
* - Stein
|
||||
- Introduced
|
Loading…
Reference in New Issue