Merge "[ovn]: port forwarding -- documentation"

doc/source/admin/ovn/features.rst

@@ -25,7 +25,7 @@ services:
 
 * DPDK
 
-  OVN and ovn mechanism driver may be used with OVS using either the Linux
+  OVN and the OVN mechanism driver may be used with OVS using either the Linux
   kernel datapath or the DPDK datapath.
 
 * Trunk driver
@@ -36,7 +36,7 @@ services:
 
 * VLAN tenant networks
 
-  The ovn driver does support VLAN tenant networks when used
+  The OVN driver does support VLAN tenant networks when used
   with OVN version 2.11 (or higher).
 
 * DNS
@@ -44,6 +44,12 @@ services:
   Native implementation. Since the version 2.8 OVN contains a built-in
   DNS implementation.
 
+* Port Forwarding
+
+  The OVN driver supports port forwarding as an extension of floating
+  IPs. Enable the 'port_forwarding' service plugin in neutron configuration
+  files to use this feature.
+
 
 The following Neutron API extensions are supported with OVN:
 
@@ -100,3 +106,5 @@ The following Neutron API extensions are supported with OVN:
 +----------------------------------+---------------------------+
 | Domain Name System (DNS)         | dns_integration           |
 +----------------------------------+---------------------------+
+| Port Forwarding                  | port_forwarding           |
++----------------------------------+---------------------------+

doc/source/ovn/gaps.rst

@@ -8,27 +8,6 @@ It is not a complete list, but is enough to be used as a starting point for
 implementors working on closing these gaps. A TODO list for OVN is located
 at [1]_.
 
-* Port forwarding
-
-  Currently ML2/OVS supports Port Forwarding in the North/South plane.
-  Specific L4 Ports of the Floating IP can be directed to a specific
-  FixedIP:PortNumber of a VM, so that different services running in a VM
-  can be isolated, and can communicate with external networks easily.
-
-  This is a relatively new extension, support would need to be added to OVN.
-
-  One possible way would be to use the OVN native load balancing feature.
-  An OVN load balancer is expressed in the OVN northbound load_balancer
-  table. Normally the VIP and its members are expressed as [2]_:
-
-  .. code-block:: console
-
-     VIP:PORT = MEMBER1:MPORT1, MEMBER2:MPORT2
-
-     The same could be extended for port forwarding as:
-
-     FIP:PORT = PRIVATE_IP:PRIV_PORT
-
 * Security Groups logging API
 
   Currently ML2/OVS, with the OpenvSwitch firewall, supports a log file where
@@ -48,9 +27,9 @@ at [1]_.
 
   Currently the Neutron L3-agent supports floating IP and gateway IP bandwidth
   limiting based on Linux TC. Networking-ovn L3 had a prototype
-  implementation [3]_ based on the meter of openvswitch [4]_ utility that
+  implementation [2]_ based on the meter of openvswitch [3]_ utility that
   has been abandoned. This is supported in user space datapath only, or
-  kernel versions 4.15+ [5]_.
+  kernel versions 4.15+ [4]_.
 
 * QoS Minimum Bandwidth support
 
@@ -67,7 +46,7 @@ at [1]_.
   The core OVN DHCP server implementation does not have support for
   sending different boot options based on the ``gpxe`` DHCP Option
   (no. 175). Also, Ironic uses dnsmasq syntax when configuring the DHCP
-  options for Neutron [6]_ which is not understood by the OVN driver.
+  options for Neutron [5]_ which is not understood by the OVN driver.
 
 * Availability Zones
 
@@ -78,7 +57,7 @@ at [1]_.
   to see how they would fit in the OVN model. For example, in the router
   availability zone case, the OVN driver should schedule the router
   ports on a Chassis (a "node" in OVN terms) where the availability
-  zones match with the router availability zones [7]_.
+  zones match with the router availability zones [6]_.
 
 * Routed provider networks
 
@@ -86,17 +65,16 @@ at [1]_.
   represent multiple L2 domains (segments). The OVN driver does not
   understand this feature yet and will need to account for multiple
   physical networks associated with a single OVN Logical Switch (a
-  network in Neutron terms) [8]_.
+  network in Neutron terms) [7]_.
 
 
 References
 ----------
 
 .. [1] https://github.com/ovn-org/ovn/blob/master/TODO.rst
-.. [2] https://github.com/ovn-org/ovn/blob/master/ovn-nb.ovsschema#L160
+.. [2] https://review.opendev.org/#/c/539826/
-.. [3] https://review.opendev.org/#/c/539826/
+.. [3] https://github.com/openvswitch/ovs/commit/66d89287269ca7e2f7593af0920e910d7f9bcc38
-.. [4] https://github.com/openvswitch/ovs/commit/66d89287269ca7e2f7593af0920e910d7f9bcc38
+.. [4] https://github.com/torvalds/linux/blob/master/net/openvswitch/meter.h
-.. [5] https://github.com/torvalds/linux/blob/master/net/openvswitch/meter.h
+.. [5] https://github.com/openstack/ironic/blob/123cb22c731f93d0c608d791b41e05884fe18c04/ironic/common/pxe_utils.py#L447-L462>
-.. [6] https://github.com/openstack/ironic/blob/123cb22c731f93d0c608d791b41e05884fe18c04/ironic/common/pxe_utils.py#L447-L462>
+.. [6] https://docs.openstack.org/neutron/latest/admin/config-az.html
-.. [7] https://docs.openstack.org/neutron/latest/admin/config-az.html
+.. [7] https://bugs.launchpad.net/neutron/+bug/1865889
-.. [8] https://bugs.launchpad.net/neutron/+bug/1865889

doc/source/ovn/index.rst

@@ -9,6 +9,7 @@ OVN Driver
    :maxdepth: 1
 
    migration.rst
+   port_forwarding.rst
    gaps.rst
    dhcp_opts.rst
    faq/index.rst

doc/source/ovn/port_forwarding.rst

@@ -0,0 +1,105 @@
+.. _port_forwarding:
+
+ML2/OVN Port forwarding
+=======================
+
+ML2/OVN supports Port Forwarding (PF) across the North/South data plane.
+Specific L4 Ports of the Floating IP (FIP) can be directed to a specific
+FixedIP:PortNumber of a VM, so that different services running in a VM
+can be isolated, and can communicate with external networks easily.
+
+OVN's native load balancing (LB) feature is used for providing this
+functionality. An OVN load balancer is expressed in the OVN northbound
+load_balancer table for all mappings for a given FIP+protocol. All PFs
+for the same FIP+protocol are kept as Virtual IP (VIP) mappings inside a
+LB entry. See the diagram below for an example of how that looks like:
+
+  .. code-block:: none
+
+     VIP:PORT = MEMBER1:MPORT1, MEMBER2:MPORT2
+
+     The same is extended for port forwarding as:
+
+     FIP:PORT = PRIVATE_IP:PRIV_PORT
+
+           Neutron DB                              OVN Northbound DB
+
+     +---------------------+              +---------------------------------+
+     | Floating IP AA      |              | Load Balancer AA UDP            |
+     |                     |              |                                 |
+     | +-----------------+ |              |                                 |
+     | | Port Forwarding | |   +----------->AA:portA => internal IP1:portX  |
+     | |                 | |   |          |                                 |
+     | | External PortA  +-----+   +------->AA:portB => internal IP2:portX  |
+     | | Fixed IP1 PortX | |       |      |                                 |
+     | | Protocol: UDP   | |       |      +---------------------------------+
+     | +-----------------+ |       |
+     |                     |       |      +---------------------------------+
+     | +-----------------+ |       |      | Load Balancer AA TCP            |
+     | | Port Forwarding | |       |      |                                 |
+     | |                 | |       |      |                                 |
+     | | External PortB  +---------+   +--->AA:portC => internal IP3:portX  |
+     | | Fixed IP2 PortX | |           |  |                                 |
+     | | Protocol: UDP   | |           |  +---------------------------------+
+     | +-----------------+ |           |
+     |                     |           |
+     | +-----------------+ |           |
+     | | Port Forwarding | |           |
+     | |                 | |           |  +---------------------------------+
+     | | External PortC  | |           |  | Load Balancer BB TCP            |
+     | | Fixed IP3 PortX +-------------+  |                                 |
+     | | Protocol: TCP   | |              |                                 |
+     | +-----------------+ |    +---------->BB:portD => internal IP4:portX  |
+     |                     |    |         |                                 |
+     +---------------------+    |         +---------------------------------+
+                                |
+                                |         +-------------------+
+                                |         | Logical Router X1 |
+     +---------------------+    |         |                   |
+     | Floating IP BB      |    |         | Load Balancers:   |
+     |                     |    |         | AA UDP, AA TCP    |
+     | +-----------------+ |    |         +-------------------+
+     | | Port Forwarding | |    |
+     | |                 | |    |         +-------------------+
+     | | External PortD  | |    |         | Logical Router Z1 |
+     | | Fixed IP4 PortX +------+         |                   |
+     | | Protocol: TCP   | |              | Load Balancers:   |
+     | +-----------------+ |              | BB TCP            |
+     +---------------------+              +-------------------+
+
+The OVN LB entries have names that include the id of the FIP and a protocol suffix.
+That protocol portion is needed because a single FIP can have multiple UDP and TCP port
+forwarding entries while a given LB entry can either be one or the other protocol (not both).
+Based on that, the format used to specify an LB entry is:
+
+  .. code-block:: ini
+
+   pf-floatingip-<NEUTRON_FIP_ID>-<PROTOCOL>
+
+A revision value is present in external_ids of each OVN load balancer entry.
+That number is synchronized with floating IP entries (NOT the port forwarding!) of the Neutron
+database.
+
+In order to differentiate a load balancer entry that was created by port forwarding
+vs load balancer entries maintained by ovn-octavia-provider, the external_ids field also
+has an owner value:
+
+  .. code-block:: python
+
+   external_ids = {
+      ovn_const.OVN_DEVICE_OWNER_EXT_ID_KEY: PORT_FORWARDING_PLUGIN,
+      ovn_const.OVN_FIP_EXT_ID_KEY: pf_obj.floatingip_id,
+      ovn_const.OVN_ROUTER_NAME_EXT_ID_KEY: rtr_name,
+      neutron:revision_number: fip_obj.revision_number,
+   }
+
+The following registry (API) neutron events trigger the OVN backend to map port forwarding
+into LB:
+
+  .. code-block:: python
+
+   @registry.receives(PORT_FORWARDING_PLUGIN, [events.AFTER_INIT])
+   def register(self, resource, event, trigger, payload=None):
+      registry.subscribe(self._handle_notification, PORT_FORWARDING, events.AFTER_CREATE)
+      registry.subscribe(self._handle_notification, PORT_FORWARDING, events.AFTER_UPDATE)
+      registry.subscribe(self._handle_notification, PORT_FORWARDING, events.AFTER_DELETE)