Merge "Add doc for share driver hooks"

doc/source/devref/index.rst

@@ -71,6 +71,7 @@ Module Reference
    services
    database
    share
+   share_hooks
    auth
    api
    scheduler

doc/source/devref/share_hooks.rst

@@ -0,0 +1,103 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Manila share driver hooks
+=========================
+
+Manila share driver hooks are designed to provide additional possibilities
+for each :term:`manila-share` service; such as any kind of notification and
+additional actions before and after share driver calls.
+
+Possibilities
+-------------
+
+- Perform actions before some share driver method calls.
+- Perform actions after some share driver method calls with results of
+    driver call and preceding hook call.
+- Call additional 'periodic' hook each 'N' ticks.
+- Possibility to update results of driver's action by post-running hook.
+
+Features
+--------
+
+- Errors in hook execution can be suppressed.
+- Any hook can be disabled.
+- Any amount of hook instances can be run at once for each manila-share
+    service.
+
+Limitations
+-----------
+
+- Hooks approach is not asynchronous. That is, if we run hooks, and
+    especially, more than one hook instance, then all of them will be executed
+    in one thread.
+
+Implementation in share drivers
+-------------------------------
+
+Share drivers can [re]define method `get_periodic_hook_data` that runs with
+each execution of 'periodic' hook and receives list of shares (as parameter)
+with existing access rules. So, each share driver, for each of its shares can
+add/update some information that will be used then in the periodic hook.
+
+What is required for writing new 'hook' implementation?
+-------------------------------------------------------
+
+All implementations of 'hook' interface are expected to be in
+'manila/share/hooks'.
+Each implementation should inherit class 'manila.share.hook:HookBase' and
+redefine its abstract methods.
+
+How to use 'hook' implementations?
+----------------------------------
+
+Just set config option 'hook_drivers' in driver's config group. For example::
+
+    [MY_DRIVER]
+    hook_drivers=path.to:FooClass,path.to:BarClass
+
+Then all classes defined above will be initialized. In the same config group,
+any config option of hook modules can be redefined too.
+
+.. note::
+
+    More info about common config options for hooks can be found in
+    module `manila.share.hook`
+
+Driver methods that are wrapped with hooks
+------------------------------------------
+
+- allow_access
+- create_share_instance
+- create_snapshot
+- delete_share_instance
+- delete_share_server
+- delete_snapshot
+- deny_access
+- extend_share
+- init_host
+- manage_share
+- publish_service_capabilities
+- shrink_share
+- unmanage_share
+
+Above list with wrapped methods can be extended in future.
+
+The :mod:`manila.share.hook.py` Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: manila.share.hook
+    :noindex:
+    :members:
+    :undoc-members:
+    :show-inheritance: