doc/source/devref/services_and_agents.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14
  15       Convention for heading levels in Neutron devref:
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21       (Avoid deeper levels because they do not render well.)
  22
  23
  24 Services and agents
  25 ===================
  26
  27 A usual Neutron setup consists of multiple services and agents running on one
  28 or multiple nodes (though some exotic setups potentially may not need any
  29 agents). Each of those services provides some of the networking or API
  30 services. Among those of special interest:
  31
  32 #. neutron-server that provides API endpoints and serves as a single point of
  33    access to the database. It usually runs on nodes called Controllers.
  34 #. Layer2 agent that can utilize Open vSwitch, Linuxbridge or other vendor
  35    specific technology to provide network segmentation and isolation for tenant
  36    networks. The L2 agent should run on every node where it is deemed
  37    responsible for wiring and securing virtual interfaces (usually both Compute
  38    and Network nodes).
  39 #. Layer3 agent that runs on Network node and provides East-West and
  40    North-South routing plus some advanced services such as FWaaS or VPNaaS.
  41
  42 For the purpose of this document, we call all services, servers and agents that
  43 run on any node as just "services".
  44
  45
  46 Entry points
  47 ------------
  48
  49 Entry points for services are defined in setup.cfg under "console_scripts"
  50 section.  Those entry points should generally point to main() functions located
  51 under neutron/cmd/... path.
  52
  53 Note: some existing vendor/plugin agents still maintain their entry points in
  54 other locations. Developers responsible for those agents are welcome to apply
  55 the guideline above.
  56
  57
  58 Interacting with Eventlet
  59 -------------------------
  60
  61 Neutron extensively utilizes the eventlet library to provide asynchronous
  62 concurrency model to its services. To utilize it correctly, the following
  63 should be kept in mind.
  64
  65 If a service utilizes the eventlet library, then it should not call
  66 eventlet.monkey_patch() directly but instead maintain its entry point main()
  67 function under neutron/cmd/eventlet/... If that is the case, the standard
  68 Python library will be automatically patched for the service on entry point
  69 import (monkey patching is done inside `python package file
  70 <http://git.openstack.org/cgit/openstack/neutron/tree/neutron/cmd/eventlet/__init__.py>`_).
  71
  72 Note: an entry point 'main()' function may just be an indirection to a real
  73 callable located elsewhere, as is done for reference services such as DHCP, L3
  74 and the neutron-server.
  75
  76 For more info on the rationale behind the code tree setup, see `the
  77 corresponding cross-project spec <https://review.openstack.org/154642>`_.
  78
  79
  80 Connecting to the Database
  81 --------------------------
  82
  83 Only the neutron-server connects to the neutron database. Agents may never
  84 connect directly to the database, as this would break the ability to do rolling
  85 upgrades.