devref: added guidelines to maintain service entry points

Change-Id: I56b3ec90045f50ba707c0b32f8ec00925dbff644

diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
index 0467ecbdb37e34946aa4efea7dd4b6c18b04c2ba..8228486462b7d07b4370a437144c3d2993f8bc53 100644 (file)
--- a/doc/source/devref/index.rst
+++ b/doc/source/devref/index.rst
@@ -38,6 +38,7 @@ Neutron Internals
 .. toctree::
    :maxdepth: 3
 
+   services_and_agents
    api_layer
    api_extensions
    plugin-api

diff --git a/doc/source/devref/services_and_agents.rst b/doc/source/devref/services_and_agents.rst
new file mode 100644 (file)
index 0000000..c7bc09e
--- /dev/null
+++ b/doc/source/devref/services_and_agents.rst
@@ -0,0 +1,54 @@
+Services and agents
+===================
+
+A usual Neutron setup consists of multiple services and agents running on one
+or multiple nodes (though some exotic setups potentially may not need any
+agents). Each of those services provides some of the networking or API
+services. Among those of special interest:
+
+#. neutron-server that provides API endpoints and serves as a single point of
+   access to the database. It usually runs on nodes called Controllers.
+#. Layer2 agent that can utilize Open vSwitch, Linuxbridge or other vendor
+   specific technology to provide network segmentation and isolation for tenant
+   networks. The L2 agent should run on every node where it is deemed
+   responsible for wiring and securing virtual interfaces (usually both Compute
+   and Network nodes).
+#. Layer3 agent that runs on Network node and provides East-West and
+   North-South routing plus some advanced services such as FWaaS or VPNaaS.
+
+For the purpose of this document, we call all services, servers and agents that
+run on any node as just "services".
+
+
+Entry points
+------------
+
+Entry points for services are defined in setup.cfg under "console_scripts"
+section.  Those entry points should generally point to main() functions located
+under neutron/cmd/... path.
+
+Note: some existing vendor/plugin agents still maintain their entry points in
+other locations. Developers responsible for those agents are welcome to apply
+the guideline above.
+
+
+Interacting with Eventlet
+-------------------------
+
+Neutron extensively utilizes the eventlet library to provide asynchronous
+concurrency model to its services. To utilize it correctly, the following
+should be kept in mind.
+
+If a service utilizes the eventlet library, then it should not call
+eventlet.monkey_patch() directly but instead maintain its entry point main()
+function under neutron/cmd/eventlet/... If that is the case, the standard
+Python library will be automatically patched for the service on entry point
+import (monkey patching is done inside `python package file
+<http://git.openstack.org/cgit/openstack/neutron/tree/neutron/cmd/eventlet/__init__.py>`_).
+
+Note: an entry point 'main()' function may just be an indirection to a real
+callable located elsewhere, as is done for reference services such as DHCP, L3
+and the neutron-server.
+
+For more info on the rationale behind the code tree setup, see `the
+corresponding cross-project spec <https://review.openstack.org/154642>`_.