Documentation: how to write a new Cerberus plugin

Change-Id: If663deff13b20aa33f593e501585b4c11e478bce

doc/source/development_plugin.rst

@@ -0,0 +1,59 @@
+===============
+Writing plugins
+===============
+
+This documentation gives you some clues on how to write a new plugin for
+Cerberus if you wish to integrate a security component which is not covered by
+an existing plugin.
+
+Cerberus manager
+================
+
+The cerberus manager is implemented in ``cerberus/manager.py``. The cerberus
+manager loads all plugins defined in the namespace ``cerberus.plugins``.
+It is also responsible of tasks management.
+
+Plugins
+=======
+
+Cerberus manager makes use of stevedore to load extensions dynamically.
+Plugins can:
+
+* subscribe to notifications sent through AMQP.
+* define a callable method (@webmethod) which will be invoked either once or
+periodically thanks to a task.
+
+Notifications
+-------------
+
+Plugins must implement:
+
+   ``process_notification(self, ctxt, publisher_id, event_type, payload, metadata):`` which receives an event message the plugin subscribed to
+
+In the ``test_plugin`` plugin, it listens to one event:
+
+* image.update
+
+Tasks
+-----
+
+For a plugin to be invoked through a task, it must implement a method with
+decorator @webmethod
+
+In the ``test_plugin`` plugin, it defines one callable method:
+
+* get_security_reports
+
+
+Adding new plugins
+------------------
+
+Cerberus needs to be easy to extend and configure so it can be tuned for each
+installation. A plugin system based on setuptools entry points makes it easy
+to add new monitors in the agents. In particular, Cerberus uses Stevedore, and
+you should put your entry point definitions in the entry_points.txt file of
+your Cerberus egg.
+Alternatively, you can put your entry point definitions in the setup.cfg file
+before installing Cerberus
+Installing a plugin automatically activates it the next time the cerberus
+manager starts.

doc/source/index.rst

@@ -41,6 +41,15 @@ API References
    webapi/v1
 
 
+Plugin development
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   development_plugin
+
+
 Indices and tables
 ==================