[ovs-dev,ovn,v2,3/7] ovn-nb: Better document distributed gateway ports.
diff mbox series

Message ID 20200318184548.3000357-4-blp@ovn.org
State New
Headers show
Series
  • gateway documentation improvements
Related show

Commit Message

Ben Pfaff March 18, 2020, 6:45 p.m. UTC
The documentation was scattered across two places.  This brings it
together.  It also documents the two solutions for physical VLAN MTU
issues in a unified way.

Signed-off-by: Ben Pfaff <blp@ovn.org>
---
 ovn-architecture.7.xml | 110 +++++++++++++++++++++++++--
 ovn-nb.xml             | 166 ++++++++++++++++++++---------------------
 2 files changed, 181 insertions(+), 95 deletions(-)

Comments

0-day Robot March 18, 2020, 6:59 p.m. UTC | #1
Bleep bloop.  Greetings Ben Pfaff, I am a robot and I have tried out your patch.
Thanks for your contribution.

I encountered some error that I wasn't expecting.  See the details below.


checkpatch:
WARNING: Line is 83 characters long (recommended limit is 79)
#218 FILE: ovn-nb.xml:2160:
                type='{"type": "string", "enum": ["set", ["overlay", "bridged"]]}'>

Lines checked: 337, Warnings: 1, Errors: 0


Please check this out.  If you feel there has been an error, please email aconole@redhat.com

Thanks,
0-day Robot

Patch
diff mbox series

diff --git a/ovn-architecture.7.xml b/ovn-architecture.7.xml
index d32978a9d5be..94a897fa693e 100644
--- a/ovn-architecture.7.xml
+++ b/ovn-architecture.7.xml
@@ -688,6 +688,100 @@ 
     highest-priority gateway that is online.
   </p>
 
+  <h4>Physical VLAN MTU Issues</h4>
+
+  <p>
+    Consider the preceding diagram again:
+  </p>
+
+  <pre fixed="yes">
+                                LSlocal
+                                   |
+                                  LR1
+                                   |
+                              +----+----+
+                              |    |    |
+                             LS1  ...  LSn
+  </pre>
+
+  <p>
+    Suppose that each logical switch LS1, ..., LSn is bridged to a physical
+    VLAN-tagged network attached to a <code>localnet</code> port on LSlocal,
+    over a distributed gateway port on LR1.  If a packet originating on
+    LS<var>i</var> is destined to the external network, OVN sends it to the
+    gateway chassis over a tunnel.  There, the packet traverses LR1's logical
+    router pipeline, possibly undergoes NAT, and eventually ends up at
+    LSlocal's <code>localnet</code> port.  If all of the physical links in the
+    network have the same MTU, then the packet's transit across a tunnel causes
+    an MTU problem: tunnel overhead prevents a packet that uses the full
+    physical MTU from crossing the tunnel to the gateway chassis (without
+    fragmentation).
+  </p>
+
+  <p>
+    OVN offers two solutions to this problem, the
+    <code>reside-on-redirect-chassis</code> and <code>redirect-type</code>
+    options.  Both solutions require each logical switch LS1, ..., LSn to
+    include a <code>localnet</code> logical switch port LN1, ..., LNn
+    respectively, that is present on each chassis.  Both cause packets to be
+    sent over the <code>localnet</code> ports instead of tunnels.  They differ
+    in which packets--some or all--are sent this way.  The most prominent
+    tradeoff between these options is that
+    <code>reside-on-redirect-chassis</code> is easier to configure and that
+    <code>redirect-type</code> performs better for east-west traffic.
+  </p>
+
+  <p>
+    The first solution is the <code>reside-on-redirect-chassis</code> option
+    for logical router ports.  Setting this option on a LRP from (e.g.) LS1 to
+    LR1 disables forwarding from LS1 to LR1 except on the gateway chassis.  On
+    chassis other than the gateway chassis, this single change means that
+    packets that would otherwise have been forwarded to LR1 are instead
+    forwarded to LN1.  The instance of LN1 on the gateway chassis then receives
+    the packet and forwards it to LR1.  The packet traverses the LR1 logical
+    router pipeline, possibly undergoes NAT, and eventually ends up at
+    LSlocal's <code>localnet</code> port.  The packet never traverses a tunnel,
+    avoiding the MTU issue.
+  </p>
+
+  <p>
+    This option has the further consequence of centralizing ``distributed''
+    logical router LR1, since no packets are forwarded from LS1 to LR1 on any
+    chassis other than the gateway chassis.  Therefore, east-west traffic
+    passes through the gateway chassis, not just north-south.  (The naive
+    ``fix'' of allowing east-west traffic to flow directly between chassis over
+    LN1 does not work because routing sets the Ethernet source address to LR1's
+    source address.  Seeing this single Ethernet source address originate from
+    all of the chassis will confuse the physical switch.)
+  </p>
+
+  <p>
+    Do not set the <code>reside-on-redirect-chassis</code> option on a
+    distributed gateway port.  In the diagram above, it would be set on the
+    LRPs connecting LS1, ..., LSn to LR1.
+  </p>
+
+  <p>
+    The second solution is the <code>redirect-chassis</code> option for
+    distributed gateway ports.  Setting this option to <code>bridged</code>
+    causes packets that are redirected to the gateway chassis to go over the
+    <code>localnet</code> ports instead of being tunneled.  This option does
+    not change how OVN treats packets not redirected to the gateway chassis.
+  </p>
+
+  <p>
+    The <code>redirect-chassis</code> option requires the administrator or the
+    CMS to configure each participating chassis with a unique Ethernet address
+    for the locgical router by setting <code>ovn-chassis-mac-mappings</code> in
+    the Open vSwitch database, for use by <code>ovn-controller</code>.  This
+    makes it more difficult to configure than
+    <code>reside-on-redirect-chassis</code>.
+  </p>
+
+  <p>
+    Set the <code>redirect-chassis</code> option on a distributed gateway port.
+  </p>
+
   <h2>Life Cycle of a VIF</h2>
 
   <p>
@@ -1892,14 +1986,14 @@ 
   </ol>
 
   <p>
-    VLAN-based redirection:
-
-    As an enhancement to <code>reside-on-redirect-chassis</code> we support
-    VLAN-based redirection as well. By setting
-    <code>options:redirect-type</code> to <code>bridged</code> on a gateway
-    chassis attached router port, user can enforce that redirected packet
-    should not use tunnel port but rather use localnet port of peer logical
-    switch to go out on a physical VLAN.
+    As an alternative to <code>reside-on-redirect-chassis</code>, OVN supports
+    VLAN-based redirection.  Whereas <code>reside-on-redirect-chassis</code>
+    centralizes all router functionality, VLAN-based redirection only changes
+    how OVN redirects packets to the gateway chassis.  By setting
+    <code>options:redirect-type</code> to <code>bridged</code> on a distributed
+    gateway port, OVN redirects packets to the gateway chassis using the
+    <code>localnet</code> port of the router's peer logical switch, instead of
+    a tunnel.
   </p>
 
   <p>
diff --git a/ovn-nb.xml b/ovn-nb.xml
index ccd9bae991af..7f142bd35031 100644
--- a/ovn-nb.xml
+++ b/ovn-nb.xml
@@ -2038,8 +2038,9 @@ 
       <p>
         If any of these are set, this logical router port represents a
         distributed gateway port that connects this router to a
-        logical switch with a localnet port.  There may be at most one
-        such logical router port on each logical router.
+        logical switch with a <code>localnet</code> port.  There may
+        be at most one such logical router port on each logical
+        router.
       </p>
 
       <p>
@@ -2096,6 +2097,82 @@ 
       <column name="options" key="redirect-chassis">
         Designates the named chassis as the gateway.
       </column>
+
+      <group title="Options for Physical VLAN MTU Issues">
+        <p>
+          MTU issues arise in mixing tunnels with logical networks that are
+          bridged to a physical VLAN.  For an explanation of the MTU issues,
+          see <code>Physical VLAN MTU Issues</code> in the OVN architecture
+          document.  The following options, which are alternatives, provide
+          solutions.  Both of them cause packets to be sent over
+          <code>localnet</code> instead of tunnels, but they differ in whether
+          some or all packets are sent this way.  The most prominent
+          tradeoff between these options is that
+          <code>reside-on-redirect-chassis</code> is easier to configure and
+          that <code>redirect-type</code> performs better for east-west
+          traffic.
+        </p>
+
+        <column name="options" key="reside-on-redirect-chassis"
+                type='{"type": "boolean"}'>
+          <p>
+            If set to <code>true</code>, this option forces all traffic across
+            the logical router port to pass through the gateway chassis using a
+            hop across a <code>localnet</code> port.  This changes behavior in
+            two ways:
+          </p>
+
+          <ul>
+            <li>
+              Without this option, east-west traffic passes directly between
+              source and destination chassis (or even within a single chassis,
+              for co-located VMs).  With this option, all east-west traffic
+              passes through the gateway chassis.
+            </li>
+
+            <li>
+              Without this option, traffic between the gateway chassis and
+              other chassis is encapsulated in tunnels.  With this option,
+              traffic passes over a <code>localnet</code> interface.
+            </li>
+          </ul>
+
+          <p>
+            This option may usefully be set only on logical router ports that
+            connect a distributed logical router to a logical switch with VIFs.
+            It should not be set on a distributed gateway port.
+          </p>
+
+          <p>
+            OVN honors this option only if the logical router has a distributed
+            gateway port and if the LRP's peer switch has a
+            <code>localnet</code> port.
+          </p>
+        </column>
+
+        <column name="options" key="redirect-type"
+                type='{"type": "string", "enum": ["set", ["overlay", "bridged"]]}'>
+          <p>
+            If set to <code>bridged</code> on a distributed gateway port, this
+            option causes OVN to redirect packets to the gateway chassis over a
+            <code>localnet</code> port instead of a tunnel.  The relevant
+            chassis must share a <code>localnet</code> port.
+          </p>
+
+          <p>
+            This feature requires the administrator or the CMS to configure
+            each participating chassis with a unique Ethernet address for the
+            locgical router by setting <code>ovn-chassis-mac-mappings</code> in
+            the Open vSwitch database, for use by <code>ovn-controller</code>.
+          </p>
+
+          <p>
+            Setting this option to <code>overlay</code> or leaving it unset has
+            no effect.  This option may usefully be set only on a distributed
+            gateway port.  It is otherwise ignored.
+          </p>
+        </column>
+      </group>
     </group>
 
     <group title="ipv6_ra_configs">
@@ -2198,91 +2275,6 @@ 
         Additional options for the logical router port.
       </p>
 
-      <column name="options" key="reside-on-redirect-chassis">
-        <p>
-          Generally routing is distributed in <code>OVN</code>. The packet
-          from a logical port which needs to be routed hits the router pipeline
-          in the source chassis. For the East-West traffic, the packet is
-          sent directly to the destination chassis. For the outside traffic
-          the packet is sent to the gateway chassis.
-        </p>
-
-        <p>
-          When this option is set, <code>OVN</code> considers this only if
-        </p>
-
-        <ul>
-          <li>
-            The logical router to which this logical router port belongs to
-            has a distributed gateway port.
-          </li>
-
-          <li>
-            The peer's logical switch has a localnet port (representing
-            a VLAN tagged network)
-          </li>
-        </ul>
-
-        <p>
-          When this option is set to <code>true</code>, then the packet
-          which needs to be routed hits the router pipeline in the chassis
-          hosting the distributed gateway router port. The source chassis
-          pushes out this traffic via the localnet port. With this the
-          East-West traffic is no more distributed and will always go through
-          the gateway chassis.
-        </p>
-
-        <p>
-          Without this option set, for any traffic destined to outside from a
-          logical port which belongs to a logical switch with localnet port,
-          the source chassis will send the traffic to the gateway chassis via
-          the tunnel port instead of the localnet port and this could cause MTU
-          issues.
-        </p>
-      </column>
-
-      <column name="options" key="redirect-type">
-        <p>
-          This options dictates if a packet redirected to
-          <code>gateway chassis</code> will be overlay encapsulated
-          or go as a regular packet via the localnet port.
-        </p>
-
-        <p>
-          Option takes following values
-        </p>
-
-        <ul>
-          <li>
-            OVERLAY
-          </li>
-
-          <li>
-            BRIDGED
-          </li>
-        </ul>
-
-        <p>
-          OVERLAY option will ensure that redirected packet goes out as
-          encapsulation via the tunnel port.
-        </p>
-
-        <p>
-          BRIDGED option will ensure that redirected packet goes out
-          via the localnet port tagged with vlan (if configured).
-        </p>
-
-        <p>
-          OVERLAY is the default redirection type.
-        </p>
-
-        <p>
-          Option is applicable only to gateway chassis attached logical
-          router ports.
-        </p>
-
-      </column>
-
       <column name="options" key="mcast_flood"
               type='{"type": "boolean"}'>
         <p>