Document existence of br-tun and br-int in the OVS agent

Question about the use of the two bridges has come up in the past
multiple times, so let's fill the gap in the developer documentation.

A user-facing documentation patch will have to follow up, if we want
to be very thorough.

Change-Id: I6dac0f9bdaf7b3b7bff8745d4103ccc71df61a0a

diff --git a/doc/source/devref/openvswitch_agent.rst b/doc/source/devref/openvswitch_agent.rst
index ae8660af3c5cbb3e189e643750ee116578382a48..6f3045a030b51d3f7ef1cd61e328c65370971c7f 100644 (file)
--- a/doc/source/devref/openvswitch_agent.rst
+++ b/doc/source/devref/openvswitch_agent.rst
@@ -36,6 +36,41 @@ More information can be found in `The VXLAN wiki page.
  <http://en.wikipedia.org/wiki/Virtual_Extensible_LAN>`_
 
 
+Bridge Management
+-----------------
+
+In order to make the agent capable of handling more than one tunneling
+technology, to decouple the requirements of segmentation technology
+from tenant isolation, and to preserve backward compatibility for OVS
+agents working without tunneling, the agent relies on a tunneling bridge,
+or br-tun, and the well known integration bridge, or br-int.
+
+All VM VIFs are plugged into the integration bridge. VM VIFs on a given
+virtual network share a common "local" VLAN (i.e. not propagated
+externally). The VLAN id of this local VLAN is mapped to the physical
+networking details realizing that virtual network.
+
+For virtual networks realized as VXLAN/GRE tunnels, a Logical Switch
+(LS) identifier is used to differentiate tenant traffic on inter-HV
+tunnels. A mesh of tunnels is created to other Hypervisors in the
+cloud. These tunnels originate and terminate on the tunneling bridge
+of each hypervisor, leaving br-int unaffected. Port patching is done
+to connect local VLANs on the integration bridge to inter-hypervisor
+tunnels on the tunnel bridge.
+
+For each virtual network realized as a VLAN or flat network, a veth
+or a pair of patch ports is used to connect the local VLAN on
+the integration bridge with the physical network bridge, with flow
+rules adding, modifying, or stripping VLAN tags as necessary, thus
+preserving backward compatibility with the way the OVS agent used
+to work prior to the tunneling capability (for more details, please
+look at https://review.openstack.org/#/c/4367).
+
+Bear in mind, that this design decision may be overhauled in the
+future to support existing VLAN-tagged traffic (coming from NFV VMs
+for instance) and/or to deal with potential QinQ support natively
+available in the Open vSwitch.
+
 Further Reading
 ---------------