diff --git a/specs/pike/support-filter-share-by-export-location.rst b/specs/pike/support-filter-share-by-export-location.rst new file mode 100644 index 0000000..84f8c4a --- /dev/null +++ b/specs/pike/support-filter-share-by-export-location.rst @@ -0,0 +1,162 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +==================================================== +Support retrieving shares filtered by export-location +==================================================== + +https://blueprints.launchpad.net/manila/+spec/support-filter-share-by-export-location + +Currently we can only filter the shares by share name, status, share type, +extra specs, share server id, metadata, snapshot, host, share network, project +id, and consistency group, but this is too limited for user's various cases. +Manila doesn't support filtering the shares by export location. This spec +intends to add the ability for Manila. + + +Problem description +=================== + +It's a common use case to list NAS shares with filters, and Manila has +the API to cover this, but it does not satisfy the situation when export +location filter is desired. The main problem is that having export location +we don't have possibility to get to know which manila share owns it. + +Use Cases +========= + +When user has a share that it has been mounted in VM, and user only knows the +share export location path. User often wants to quickly filter a share by +share export location in Manila. This change will help him achieve this. + +Proposed change +=============== + +The modified version of shares and share-instances list will be identical at +the most part, except for the parts mentioned below: + +* A query parameter 'export_location' will be introduced to shares and + share-instances list API (GET shares and GET shares/detail, GET + share-instances and GET share-instances/detail). +* In the API service, the export_location will be added in share and share + instance search options. In Manila DB's method, will add a new export + location filter in SQLAlchemy API, and add a new logic which would filter + all the shares or share instances with the export location. +* The Manila client will also add one argument '--export_location' to support + this. + +Alternatives +------------ + +We could get share instance ID from share export location path, and use +"share-instance-show " command to find out associated share. + +Data model impact +----------------- + +None + +REST API impact +--------------- + +The API microversion will have to be bumped up for the new APIs below. + +Share and share-instances list API will accept new query string parameter +'export_location'. Administrators can pass path and id of export_location +to retrieve shares filtered. + +* ``GET /v2/{tenant_id}/shares?export_location=test_path`` +* ``GET /v2/{tenant_id}/share-instances?export_location=test_path`` + +Detailed share and share-instance list API will also accept new query string +parameter 'export_location'. Administrator can pass path and id of the export +location to retrieve shares filtered. + +* ``GET /v2/{tenant_id}/shares/detail?export_location=test_path`` +* ``GET /v2/{tenant_id}/share-instances/detail?export_location=test_path`` + +The search will be among "allowed", for user, shares - all his shares and +public ones. + +Manila client impact +-------------------- + +Manila client will add a new parameter '--export_location ' +to command 'list', the modified version of command will be like:: + +* list --export_location +* share-instance-list --export_location + + +Security impact +--------------- + +None + +Notifications impact +-------------------- + +None. + +Other end user impact +--------------------- + +None. + +Performance Impact +------------------ + +None + +Other deployer impact +--------------------- + +None + +Developer impact +---------------- + +None + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + zhongjun2(jun.zhongjun2@gmail.com) + + +Work Items +---------- + +* Add 'export_location' parameter to 'list' collection. +* Add related tests in Manila. +* Add documentation in Manila. +* Add new argument for command 'list' in Manila client. +* Add related tests in Manila client. + +Dependencies +============ + +None + + +Testing +======= + +1. Unit and tempest tests whether new API works correctly. +2. Manila client's unit tests and functional tests on new added argument. + +Documentation Impact +==================== + +1. The Manila API documentation will need to be updated to reflect the REST + API changes. + +References +==========