ovn: Constrain supported tunnel types.

Limit the supported tunnel types to Geneve and STT on hypervisors, and
VXLAN, Geneve, and STT on gateways.  This commit adds "DESIGN.md" that
describes the reasoning.

Wes Felter provided suggestions for improving the wording in the
architecture document.

Signed-off-by: Justin Pettit <jpettit@nicira.com>
Acked-by: Ben Pfaff <blp@nicira.com>

6 files changed, 65 insertions, 10 deletions

diff --git a/ovn/TODO b/ovn/TODO
index 41f4d91d8..209a315b9 100644
--- a/ovn/TODO
+++ b/ovn/TODO
@@ -91,10 +91,6 @@
 
 ** ovn-controller parameters and configuration.
 
-*** Tunnel encapsulation to publish.
-
-    Default: VXLAN? Geneve?
-
 *** SSL configuration.
 
     Can probably get this from Open_vSwitch database.
diff --git a/ovn/controller/ovn-controller.8.xml b/ovn/controller/ovn-controller.8.xml
index 5d4c595a2..e1cb6a228 100644
--- a/ovn/controller/ovn-controller.8.xml
+++ b/ovn/controller/ovn-controller.8.xml
@@ -97,8 +97,10 @@
           <p>
             <code>external_ids:ovn-encap-type</code> specifies the
             encapsulation type that a chassis should use to connect to
-            this node.  Examples include <code>geneve</code>,
-            <code>vxlan</code>, and <code>stt</code>.
+            this node.  Supported tunnel types for connecting
+            hypervisors are <code>geneve</code> and <code>stt</code>.
+            Gateways may use <code>geneve</code>, <code>vxlan</code>,
+            or <code>stt</code>.
           </p>
         </li>
         <li>
diff --git a/ovn/ovn-architecture.7.xml b/ovn/ovn-architecture.7.xml
index f1dfa5fdf..f0921410b 100644
--- a/ovn/ovn-architecture.7.xml
+++ b/ovn/ovn-architecture.7.xml
@@ -575,4 +575,58 @@
       to reflect the update.
     </li>
   </ol>
+
+  <h1>Design Decisions</h1>
+
+  <h2>Supported Tunnel Encapsulations</h2>
+  <p>
+    For connecting hypervisors to each other, the only supported tunnel
+    encapsulations are Geneve and STT. Hypervisors may use VXLAN to
+    connect to gateways. We have limited support to these encapsulations
+    for the following reasons:
+  </p>
+
+  <ul>
+    <li>
+      <p>
+        They support large amounts of metadata.  In addition to
+        specifying the logical switch, we will likely want to indicate
+        the logical source port and where we are in the logical
+        pipeline.  Geneve supports a 24-bit VNI field and TLV-based
+        extensions.  The header of STT includes a 64-bit context id.
+      </p>
+    </li>
+
+    <li>
+      <p>
+        They use randomized UDP or TCP source ports that allows
+        efficient distribution among multiple paths in environments that
+        use ECMP in their underlay.
+      </p>
+    </li>
+
+    <li>
+      <p>
+        NICs are available that accelerate encapsulation and decapsulation.
+      </p>
+    </li>
+  </ul>
+
+  <p>
+    Due to its flexibility, the preferred encapsulation between
+    hypervisors is Geneve.  Some environments may want to use STT for
+    performance reasons until the NICs they use support hardware offload
+    of Geneve.
+  </p>
+
+  <p>
+    For connecting to gateways, the only supported tunnel encapsulations
+    are VXLAN, Geneve, and STT.  While support for Geneve is becoming
+    available for TOR (top-of-rack) switches, VXLAN is far more common.
+    Currently, gateways have a feature set that matches the capabilities
+    as defined by the VTEP schema, so fewer bits of metadata are
+    necessary.  In the future, gateways that do not support
+    encapsulations with large amounts of metadata may continue to have a
+    reduced feature set.
+  </p>
 </manpage>
diff --git a/ovn/ovn-sb.ovsschema b/ovn/ovn-sb.ovsschema
index 9fd5363b2..363e664a0 100644
--- a/ovn/ovn-sb.ovsschema
+++ b/ovn/ovn-sb.ovsschema
@@ -17,7 +17,9 @@
             "indexes": [["name"]]},
         "Encap": {
             "columns": {
-                "type": {"type": "string"},
+                "type": {"type": {"key": {
+                           "type": "string",
+                           "enum": ["set", ["geneve", "stt", "vxlan"]]}}},
                 "options": {"type": {"key": "string",
                                      "value": "string",
                                      "min": 0,
diff --git a/ovn/ovn-sb.xml b/ovn/ovn-sb.xml
index 29a1c885f..2afc9a190 100644
--- a/ovn/ovn-sb.xml
+++ b/ovn/ovn-sb.xml
@@ -166,8 +166,9 @@
 
     <column name="type">
       The encapsulation to use to transmit packets to this chassis.
-      Examples include <code>geneve</code>, <code>vxlan</code>, and
-      <code>stt</code>.
+      Hypervisors must use either <code>geneve</code> or
+      <code>stt</code>.  Gateways may use <code>vxlan</code>,
+      <code>geneve</code>, or <code>stt</code>.
     </column>
 
     <column name="options">
diff --git a/tutorial/ovs-sandbox b/tutorial/ovs-sandbox
index 8aa2ddd49..1520cb734 100755
--- a/tutorial/ovs-sandbox
+++ b/tutorial/ovs-sandbox
@@ -289,7 +289,7 @@ rungdb $gdb_vswitchd ovs-vswitchd --detach --no-chdir --pidfile -vconsole:off --
 if $ovn; then
     ovs-vsctl set open . external-ids:system-id=56b18105-5706-46ef-80c4-ff20979ab068
     ovs-vsctl set open . external-ids:ovn-remote=unix:"$sandbox"/db.sock
-    ovs-vsctl set open . external-ids:ovn-encap-type=vxlan
+    ovs-vsctl set open . external-ids:ovn-encap-type=geneve
     ovs-vsctl set open . external-ids:ovn-encap-ip=127.0.0.1
     ovs-vsctl add-br br-int