From 933dee471e209879426e207fa41ef0bea4d93675 Mon Sep 17 00:00:00 2001
From: Romain Ziba <romain.ziba@eurogiciel.fr>
Date: Mon, 8 Jun 2015 16:53:00 +0200
Subject: [PATCH] Documentation: how to write a new Cerberus plugin

Change-Id: If663deff13b20aa33f593e501585b4c11e478bce
---
 doc/source/development_plugin.rst | 59 +++++++++++++++++++++++++++++++
 doc/source/index.rst              |  9 +++++
 2 files changed, 68 insertions(+)
 create mode 100644 doc/source/development_plugin.rst

diff --git a/doc/source/development_plugin.rst b/doc/source/development_plugin.rst
new file mode 100644
index 0000000..eea5ece
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0c4e62f..50374d8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -41,6 +41,15 @@ API References
    webapi/v1
 
 
+Plugin development
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   development_plugin
+
+
 Indices and tables
 ==================