From 18351a960b0167528620d515f045b3aaa6486ba8 Mon Sep 17 00:00:00 2001 From: "john.griffith8@gmail.com" Date: Fri, 3 Mar 2017 16:05:41 -0700 Subject: [PATCH] Propose use of generalized resource filtering Stop creating ad-hoc filter parameters for cinder list calls. Just use generic filters with k/v pairs and get on with life. Change-Id: I44cf473d560a2d335a9607eb14f57ffc62092934 blueprint: generalized-filtering-for-cinder-list-resource --- specs/pike/generalized_list_filters.rst | 155 ++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 specs/pike/generalized_list_filters.rst diff --git a/specs/pike/generalized_list_filters.rst b/specs/pike/generalized_list_filters.rst new file mode 100644 index 00000000..f2305e29 --- /dev/null +++ b/specs/pike/generalized_list_filters.rst @@ -0,0 +1,155 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +============================================================ +Generalized filtered listing on resources +============================================================ + +https://blueprints.launchpad.net/cinder/+spec/generalized-filtering-for-cinder-list-resource + +Problem description +=================== +We continue adding various filter options to the Cinder List API's. Things +like "filter results by x=y". This results in a good deal of code being +added for one-off preferences or user convenience. It also means that we +continue to bump micro-versions for such additions and create more versions +of the API than we probably care to document, test and maintain. + +What's annoying about this is that it's not even that we're adding things +to the server side, we're instead just popping things off of the params +in the request body based on what micro-version is specified. + +The biggest area of churn for this sort of thing is in the client side of +things. + +Use Cases +========= +Filters are convenient for operators doing things with large clouds. It's +certainly a nice-to-have feature to be able to do things like just ask +Cinder for a list of all volumes with an `error` status, or that are +`bootable` or the latest, suggestion all those that are attached to host +xyz. + +Proposed change +=============== +In order to add these today, we add a specific arg to the clients, and then +we add specific arg parsing on the Cinder API server to interpret and parse +these args. These parsed arguments are then just used to build a filter that +we pass in to the sql call to get_volumes (or get_). + +Rather than continuing to add these for the various resources in an ad-hoc +manner, this spec proposes a generalized filtered-list mechanism. Rather +than add a specific filter by name over and over, instead provide a single +`filter` argument that supplies Key Value pairs to be used to build the +db query filter. There's likely some concern that people won't *know* what +valid filter keys are, for that we can also provide a `list-filters` command +that could be used in an introspective sort of way, querying the object model +for the valid filter items and returning it to the caller. + +The `list-filters` component is derived from an Admin provided list of valid +and enabled filters for end users to access. This obviously serves two +purposes: + + 1. Advertise what filters are enabled/available to the end user + 2. Gives the Cloud Operator the ability to pick what filters are enabled + +It's important to note that not all clouds will want to expose filters like +backend-host and other internals that shouldn't typically be leaked to the +end user. + +What's interesting about this is from the API Servers perspective we don't +even really care about any of this. We can already pass in filters via +the params in the request body and this just works. If you're using curl +this just works already as is. If you are using the client you'd just need +a way to expose it properly: +(https://gist.github.com/j-griffith/f455e51d3e597af96bfe7022974b5bd9) + + +Alternatives +------------ +* We could certainly continue doing what we're doing now and just adding + specific filter arguments to the clients and the API, but I don't think + that's sustainable. + +* We could provide a generalized "filters" (pick a better name) controller + that could be called directly and then call the specified resource item + with filters. This would mean you would do things like: + `cinder filters-list --resource volume` to get a list of valid filter + items for a volume (volumes should be the default). + + `cinder filters-list --resource snapshot` for snapshots, etc. + + But then have something like a `cinder filtered-list --filter xyz=abc` + which would go to a filtered-list controller and then call the resource + controller appropriately. + + This might be a good way to reduce some duplicate code and churn even further + but it may require just as much work and code as just having each resource + have it's own "--filter" options to the list commands. + +Data model impact +----------------- +None + +REST API impact +--------------- +Other than adding the ability to view the valid filter keys we don't +even need to change anything on the Cinder server side currently. + +Security impact +--------------- +None that I'm aware of + +Notifications impact +-------------------- + + +Other end user impact +--------------------- +Life would be better + +Performance Impact +------------------ +None + +Other deployer impact +--------------------- +None + +Developer impact +---------------- +Life would be better + + +Implementation +============== + +Assignee(s) +----------- +Primary assignee: + john-griffith + + +Work Items +---------- +* Add the filters arg to the client +* Add the ability to query the API server + for valid filters for a resource + +Dependencies +============ + +Testing +======= + +Documentation Impact +==================== +We will need to update documentation to describe the new capability, +although I expect anybody not using the client may already be exposing +this on their own. + +References +==========