[ovs-dev] [PATCH] ovn-architecture: Start describing how to connect to physical networks.

[Ben Pfaff]

Signed-off-by: Ben Pfaff <blp at nicira.com>
---
 ovn/ovn-architecture.7.xml | 83 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/ovn/ovn-architecture.7.xml b/ovn/ovn-architecture.7.xml
index 318555b..8ae148e 100644
--- a/ovn/ovn-architecture.7.xml
+++ b/ovn/ovn-architecture.7.xml
@@ -309,6 +309,89 @@
     </li>
   </ul>
 
+  <h2>Connecting Logical Networks to Physical Networks</h2>
+
+  <p>
+    Logical networks can be useful by themselves for use within a cloud, but
+    ordinarily at least some part of a cloud deployment will need to connect to
+    external physical networks.  OVN supports multiple ways to connect to
+    physical networks.  These methods can be classified along two axes.
+  </p>
+
+  <p>
+    The first axis is the <dfn>connection point</dfn>.  Physical networks can
+    be <em>connected at hypervisors</em>.  To access a physical network in this
+    fashion, a VM must run on a hypervisor that is directly connected to that
+    network, that is, its hypervisor must be on the physical network's subnet.
+    Alternatively, physical networks can be <em>centrally connected</em>, with
+    packets passing through a tunnel to a central point.  This model does not
+    require hypervisors to have a direct connection to the physical network,
+    but it does require setting up and maintaining a central gateway.
+  </p>
+
+  <p>
+    The second axis is the <dfn>degree of NAT</dfn> (network address
+    translation).  The lowest level of NAT is <em>no NAT</em>, in which VMs are
+    directly assigned physical network IP addresses.  The next level is <em>IP
+    address translation</em>, which translates IP addresses.  This allows
+    physical and logical IP addresses to be separately allocated.  Finally,
+    <em>(full) NAT</em> translates IP addresses and transport port numbers.
+    Only full NAT allows multiple VMs to share a public IP address.
+  </p>
+
+  <p>
+    These axes are independent.  Each pairing yields a different design:
+  </p>
+
+  <dl>
+    <dt>No NAT, connected at hypervisors</dt>
+    <dd>
+      <p>
+        This design extends external IP addresses directly into VMs.  A CMS can
+        implement this design with OVN using <code>localnet</code> ports.  VLAN
+        tagging is optional.
+      </p>
+
+      <p>
+        OVN doesn't add any value to this kind of physical network
+        connectivity, because plugging the VM's interface directly into a
+        physical network bridge works just as well.  OVN provides this option
+        for use by CMSes (e.g. OpenStack Neutron) that require all of the
+        network connectivity on a hypervisor to go through a single networking
+        provider (i.e. OVN).
+      </p>
+    </dd>
+
+    <dt>IP address translation, connected at hypervisors</dt>
+    <dd>
+      <p>
+        This design uses separate ranges of external and internal IP addresses
+        and translates addresses in IP and ARP packets that cross in either
+        direction.
+      </p>
+
+      <p>
+        OVN will implement direct support for this case.  For now, one can
+        implement it with an <code>localnet</code> port that patches to an
+        isolated bridge.  Configure the desired public IP address on the
+        bridge, plus the private IP address's gateway IP.  Then use
+        <code>iptables</code> rules to translate addresses.  For example, with
+        private IP <code>$PRV</code> and public IP <code>$PUB</code> that is
+        routed to physical network device <code>$ETH</code>:
+      </p>
+
+      <pre>
+iptables -t nat -A POSTROUTING -s $PRV -o $ETH -j SNAT --to-source $PUB
+iptables -t nat -A PREROUTING -d $PUB -i $ETH -j DNAT --to-destination $PRV
+      </pre>
+    </dd>
+
+    <dt>Other pairings</dt>
+    <dd>
+      OVN will implement support for other pairings as well.  Details TBD.
+    </dd>
+  </dl>
+
   <h2>Life Cycle of a VIF</h2>
 
   <p>
-- 
2.1.3