Add networking scenarios for ml2 with l2pop

This patch add a new section for the ML2 plugin
in networking scenarios section.

Also add 2 first scenarios with ML2 and the
L2 population mechanism driver.

Closes-Bug: #1252703
Change-Id: Iac01b03cb94b1bddc75a3f1fa81c198914ee49ea

doc/config-reference/networking/section_networking-scenarios.xml

@@ -574,4 +574,65 @@ physical_interface_mappings = physnet2:eth1</programlisting></para>
         </section>
         </section>
     </section>
+    <section xml:id="ml2_scenarios">
+        <title>ML2</title>
+        <para>The Modular Layer 2 plugin allows OpenStack
+            Networking to simultaneously utilize the variety of layer 2 networking
+            technologies found in complex real-world data centers.
+            It currently includes drivers for the local, flat, vlan, gre and vxlan network types
+            and works with the existing <emphasis>Open vSwitch</emphasis>, <emphasis>Linux Bridge</emphasis>,
+            and <emphasis>HyperV</emphasis> L2 agents. The <emphasis>ML2</emphasis> plug-in can be extended
+            through mechanism drivers, multiple mechanisms can be used simultaneously.
+            This section describes different <emphasis>ML2</emphasis> plug-in / agents configurations with different
+            type drivers and mechanism drivers.</para>
+        <section xml:id="ml2_l2pop_scenarios">
+            <title>ML2 with L2 population mechanism driver</title>
+            <para>Current <emphasis>Open vSwitch</emphasis> and <emphasis>Linux Bridge</emphasis> tunneling implementations
+                broadcast to every agent, even if they don’t host the corresponding network as
+                illustrated below.</para>
+             <mediaobject>
+                 <imageobject>
+                    <imagedata fileref="../../common/figures/ml2_without_l2pop_full_mesh.png"
+                        contentwidth="6in"/>
+                 </imageobject>
+             </mediaobject>
+            <para>As broadcast emulation on overlay is costly, it may be better to avoid its use for
+                mac learning and ARP resolution. This supposes the use of proxy ARP on the agent to
+                answer VM requests, and to populate forwarding table. Currently only the <emphasis>Linux Bridge</emphasis> Agent implements an ARP proxy. The prepopulation limits L2 broadcasts in overlay, however it may anyway be necessary to provide broadcast emulation.
+                This is achieved by sending broadcasts packets over unicasts only to the relevant
+                agents as illustrated below.<mediaobject>
+                    <imageobject>
+                        <imagedata fileref="../../common/figures/ml2_without_l2pop_partial_mesh.png"
+                            contentwidth="6in"/>
+                    </imageobject>
+                </mediaobject>The partial-mesh is available with the <emphasis>Open vSwitch</emphasis> and
+                the <emphasis>Linux Bridge</emphasis> agent. The following scenarios will use the L2
+                population mechanism driver with an <emphasis>Open vSwitch</emphasis> agent and a <emphasis>Linux Bridge</emphasis> agent. To enable the l2 population driver we have to add it in the list of mechanism drivers. We also need to have at least one tunneling
+                type driver enabled, either GRE, VXLAN or both. Below configuration options that we
+                have to set in
+                <filename>ml2_conf.ini</filename>:<programlisting language="ini">[ml2]
+type_drivers = local,flat,vlan,gre,vxlan
+mechanism_drivers = openvswitch,linuxbridge,l2population</programlisting></para>
+        </section>
+        <section xml:id="ml2_l2pop_ovs_scenarios">
+            <title>Scenario 1: L2 population with Open vSwitch agent</title>
+            <para>We have to enable the l2 population extension on the <emphasis>Open vSwitch</emphasis> agent side and
+                we also have to set the <option>local_ip</option> parameter and the <option>tunnel_types</option>
+                <filename>ml2_conf.ini</filename>.<programlisting language="ini">[ovs]
+local_ip = <replaceable>192.168.1.10</replaceable>
+
+[agent]
+tunnel_types = <replaceable>gre</replaceable>,<replaceable>vxlan</replaceable>
+l2_population = True</programlisting></para>
+        </section>
+        <section xml:id="ml2_l2pop_lb_scenarios">
+            <title>Scenario 1: L2 population with <emphasis>Linux Bridge</emphasis> agent</title>
+            <para>We have to enable the l2 population extension on the agent side and we also have
+                to set the local_ip parameter and enable VXLAN in
+                <filename>ml2_conf.ini</filename>.<programlisting language="ini">[vxlan]
+enable_vxlan = True
+local_ip = <replaceable>192.168.1.10</replaceable>
+l2_population = True</programlisting></para>
+        </section>
+    </section>
 </section>