diff --git a/doc/source/hooks.rst b/doc/source/hooks.rst deleted file mode 100644 index 5d6b09d2e94b..000000000000 --- a/doc/source/hooks.rst +++ /dev/null @@ -1,57 +0,0 @@ -Hooks -===== - -Hooks provide a mechanism to extend Nova with custom code through a plugin -mechanism. - -Named hooks are added to nova code via a decorator that will lazily load -plugin code matching the name. The loading works via setuptools -`entry points`_. - -.. _`entry points`: http://pythonhosted.org/setuptools/pkg_resources.html#entry-points - -What are hooks good for? ------------------------- - -Hooks are good for anchoring your custom code to Nova internal APIs. - -What are hooks NOT good for? ----------------------------- - -Hooks should not be used when API stability is a key factor. Internal APIs may -change. Consider using a notification driver if this is important to you. - -Declaring hooks in the Nova codebase ------------------------------------- - -The following example declares a *resize_hook* around the *resize_instance* method:: - - from nova import hooks - - @hooks.add_hook("resize_hook") - def resize_instance(self, context, instance, a=1, b=2): - ... - -Hook objects can now be attached via entry points to the *resize_hook*. - -Adding hook object code ------------------------ - -1. Setup a Python package with a setup.py file. -2. Add the following to the setup.py setup call:: - - entry_points = { - 'nova.hooks': [ - 'resize_hook=your_package.hooks:YourHookClass', - ] - }, - -3. *YourHookClass* should be an object with *pre* and/or *post* methods:: - - class YourHookClass(object): - - def pre(self, *args, **kwargs): - .... - - def post(self, rv, *args, **kwargs): - .... diff --git a/doc/source/index.rst b/doc/source/index.rst index abb09e252138..4e630a5ee4d0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -153,7 +153,6 @@ Open Development. i18n filter_scheduler rpc - hooks block_device_mapping addmethod.openstackapi conductor diff --git a/nova/hooks.py b/nova/hooks.py index 35bc3af29d49..bb85f38ee994 100644 --- a/nova/hooks.py +++ b/nova/hooks.py @@ -16,6 +16,9 @@ """Decorator and config option definitions for adding custom code (hooks) around callables. +NOTE: as of Nova 13.0 hooks are DEPRECATED and will be removed in the +near future. You should not build any new code using this facility. + Any method may have the 'add_hook' decorator applied, which yields the ability to invoke Hook objects before or after the method. (i.e. pre and post) @@ -47,7 +50,7 @@ import functools from oslo_log import log as logging import stevedore -from nova.i18n import _, _LE +from nova.i18n import _, _LE, _LW LOG = logging.getLogger(__name__) NS = 'nova.hooks' @@ -82,6 +85,8 @@ class HookManager(stevedore.hook.HookManager): obj = e.obj hook_method = getattr(obj, method_type, None) if hook_method: + LOG.warning(_LW("Hooks are deprecated as of Nova 13.0 and " + "will be removed in a future release")) LOG.debug("Running %(name)s %(type)s-hook: %(obj)s", {'name': name, 'type': method_type, 'obj': obj}) try: diff --git a/releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml b/releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml new file mode 100644 index 000000000000..6990935e7d06 --- /dev/null +++ b/releasenotes/notes/deprecate_hooks-6f6d60ac206a6da6.yaml @@ -0,0 +1,7 @@ +--- +deprecations: + - Deprecate the use of nova.hooks. This facility used to let + arbitrary out of tree code be executed around certain internal + actions, but is unsuitable for having a well maintained + API. Anyone using this facility should bring forward their use + cases in the Newton cycle as nova-specs.