Allow to filter resources by inexact value matching in 'list' APIs

This spec proposes changing API filter behavior to inexact matching of filter
values.

Partially-Implements BP like-filter
Change-Id: I9ef69612224211c06fd2a2b086d7da24bcb68222
This commit is contained in:
zhongjun 2017-03-21 11:06:00 +08:00 committed by zhongjun
parent e718599a43
commit 79006e98a2
1 changed files with 234 additions and 0 deletions

234
specs/pike/like-filter.rst Normal file
View File

@ -0,0 +1,234 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================
Flexible API filters
=====================
https://blueprints.launchpad.net/manila/+spec/like-filter
This spec proposes changing API filter behavior to inexact matching of filter
values.
Problem description
===================
Currently, we could only filter manila resource by exact match. This is
not flexible enough, because customer needs to remember full share name,
and can not get shares quickly by key words. However for customer, if partly
alike filters are supported to retrieve the shares via user input, that
should be useful for user to filter shares by name flexibly, especially for
the users who have a lot of shares which are managed by manila.
By the way, it's already introduced in many other projects, we can take
advantage of those some existing mechanism, nova `[1]`_ and ironic `[2]`_.
In nova, it change for regex filter matching in sqlalchemy. In ironic, it
add a way to filter nodes in the API by their name (regex and wildcard).
Use Cases
=========
User has really big amount of shares. He named them using some different
templates based on his needs. And he may want to filter out shares based
on some part of share names. The same situation with "description".
Proposed change
===============
It's worth to mention here, that this feature is also been proposed in
cinder `[4]`_ and it's depended on the generalized resource filter
`[5]`_ , but making the API behavior configurable is still open to
question in manila, so we would only pick the part we'd like to have
while keep the API consistency with cinder.
Use '~' operator after the filter key to trigger the like filtering
operation, this is also how our API will look like::
GET /v2/<tenant_id>/shares?name~=test
Support like filter only on specified resources (cinder let the
administrator to have that decision by configuration file):
* list shares (name, description)
* list snapshots (name, description)
* list share-networks (name, description)
* list share-groups (name, description)
The Manila client will add a new command argument '--name~' and
'--description~' to 'list' APIs to filter manila resources by inexact match.
We can provide resource filtering based on regex filter, but there
is a possibility that we could have ReDos `[3]`_ attack. Considering the
filter is flexible and safe enough for this case. We could introduce 'LIKE'
operator. And we can easily apply this filter at the existing sqlalchemy
filtering function, and use 'LIKE' operator to filtering resource.
Alternatives
------------
There is an option that we can deploy searchlight which mainly focus on
various cloud resource querying, and that's a more wider topic. But we
should also consider the cloud environment that don't contain searchlight.
Also, there is another option that user can gather all the raw data and
do the filtering on their own, but it's obvious that is what we try
to avoid, cause it costs a lot of unnecessary resource expense.
Data model impact
-----------------
None
REST API impact
---------------
Microversion bump is required for this change.
* Add ``name~`` and ``description~`` parameter to list API
interfaces. It means we can use this new parameter to inexact filtering::
List shares with share name
GET /v2/<tenant_id>/shares?name~=test
Accept: application/json
JSON Response
{
"shares": [
{
"status": "available",
"export_location": %ip%:/opt/stack/data/manila/mnt/share-%share_id%,
"name": "test_1",
...
},
{
"status": "available",
"export_location": null,
"name": "2_test",
...
}
]
}
List snapshot with share snapshot name
GET /v2/<tenant_id>/snapshots?name~=snap_test
Accept: application/json
JSON Response
{
"shares": [
{
"status": "available",
"name": "snap_test_1",
...
},
{
"status": "available",
"name": "snap_test_xxxxx",
...
}
]
}
Client impact
-------------
The Manila client will add a new command argument '--name~'
and '--description~' to 'list' to filter manila resource by inexact match::
manila list [--name~ <name~>] [--description~ <description~>]
We assuming we have two shares in the name of'test_1', '2_test', usually we
would get none of them if type this command::
manila list --name test
But within this feature merged, we would have both of them with the identical
command if type this command::
manila list --name~ test
Security impact
---------------
None
Notifications impact
--------------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
Developer should update the filtering function to support exact/inexact filter
(use 'LIKE' operator to filtering resource) in DB API whenever the list/show
API changed.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
tommylikehu(tommylikehu@gmail.com)
jun.zhongjun(jun.zhongjun2@gmail.com)
Work Items
----------
* Functional tests
* Implement core feature
* Add related unit tests
* Update python-manilaclient
Dependencies
============
None
Testing
=======
* Add unit tests and functional tests to cover filter process change.
Documentation Impact
====================
Update API documentation.
References
==========
It is proposing essentially the same spec for cinder `[5]`_.
_`[1]`: https://review.openstack.org/#/c/45026/
_`[2]`: https://review.openstack.org/#/c/266688/
_`[3]`: https://en.wikipedia.org/wiki/ReDoS
_`[4]`: https://review.openstack.org/#/c/442982/
_`[5]`: https://review.openstack.org/#/c/441516/