[OVN][Doc] Update docs for Routed Provider Networks

Add documentation for Routed Provider Networks.

Co-Authored-By: Lucas Alvares Gomes <lucasagomes@gmail.com>
Closes-Bug: #1865889
Change-Id: Ie9b7ba52b5b9e93480f22d6863038bea23a19123

doc/source/admin/ovn/features.rst

@@ -56,6 +56,21 @@ services:
   packets for relevant resources when the registered events occur. OVN supports
   this feature based on security groups.
 
+* Segments
+
+  Allows for Network segments ranges to be used with OVN. Requires OVN
+  version 20.06 or higher.
+
+.. TODO What about tenant networks?
+
+* Routed provider networks
+
+  Allows for multiple localnet ports to be attached to a single Logical
+  Switch entry. This work also assumes that only a single localnet
+  port (of the same Logical Switch) is actually mapped to a given
+  hypervisor. Requires OVN version 20.06 or higher.
+
+
 The following Neutron API extensions are supported with OVN:
 
 +----------------------------------+---------------------------+
@@ -75,6 +90,8 @@ The following Neutron API extensions are supported with OVN:
 +----------------------------------+---------------------------+
 | Network IP Availability          | network-ip-availability   |
 +----------------------------------+---------------------------+
+| Network Segment                  | segment                   |
++----------------------------------+---------------------------+
 | Neutron external network         | external-net              |
 +----------------------------------+---------------------------+
 | Neutron Extra DHCP opts          | extra_dhcp_opt            |

doc/source/admin/ovn/index.rst

@@ -15,3 +15,4 @@ OVN Driver Administration Guide
    troubleshooting
    sriov
    router_availability_zones
+   routed_provider_networks

doc/source/admin/ovn/routed_provider_networks.rst

@@ -0,0 +1,88 @@
+.. _routed_provider_networks:
+
+================================
+Routed Provider Networks for OVN
+================================
+
+The Routed Provider Networks feature is used to present a multi-segmented
+layer-3 network as a single entity in Neutron.
+
+After creating a provider network with multiple segments as described
+in the :ref:`Neutron documentation<config-routed-provider-networks>`,
+each segment connects to a provider ``Local_Switch`` entry as
+``Logical_Switch_Port`` entries with the ``localnet`` port type.
+
+For example, in the OVN Northbound database, this is how a VLAN
+Provider Network with two segments (VLAN: 100, 200) is related to their
+``Logical_Switch`` counterpart:
+
+  .. code-block:: bash
+
+     $ ovn-nbctl list logical_switch public
+     _uuid               : 983719e5-4f32-4fb0-926d-46291457ca41
+     acls                : []
+     dns_records         : []
+     external_ids        : {"neutron:mtu"="1450", "neutron:network_name"=public, "neutron:revision_number"="3"}
+     forwarding_groups   : []
+     load_balancer       : []
+     name                : neutron-6c8be12a-9ed0-4ac4-8130-cb8fad83cd46
+     other_config        : {mcast_flood_unregistered="false", mcast_snoop="true"}
+     ports               : [81bce1ab-87f8-4ed5-8163-f16701499dfe, b23d0c2e-773b-4ecb-8306-53d117006a7b]
+     qos_rules           : []
+
+     $ ovn-nbctl list logical_switch_port 81bce1ab-87f8-4ed5-8163-f16701499dfe
+     _uuid               : 81bce1ab-87f8-4ed5-8163-f16701499dfe
+     addresses           : [unknown]
+     dhcpv4_options      : []
+     dhcpv6_options      : []
+     dynamic_addresses   : []
+     enabled             : []
+     external_ids        : {}
+     ha_chassis_group    : []
+     name                : provnet-96f663af-19fa-4c7e-a1b8-1dfdc9cd9e82
+     options             : {network_name=phys-net-1}
+     parent_name         : []
+     port_security       : []
+     tag                 : 100
+     tag_request         : []
+     type                : localnet
+     up                  : false
+
+     $ ovn-nbctl list logical_switch_port b23d0c2e-773b-4ecb-8306-53d117006a7b
+     _uuid               : b23d0c2e-773b-4ecb-8306-53d117006a7b
+     addresses           : [unknown]
+     dhcpv4_options      : []
+     dhcpv6_options      : []
+     dynamic_addresses   : []
+     enabled             : []
+     external_ids        : {}
+     ha_chassis_group    : []
+     name                : provnet-469cbc3d-8e06-4a8f-be3a-3fcdadfd398a
+     options             : {network_name=phys-net-2}
+     parent_name         : []
+     port_security       : []
+     tag                 : 200
+     tag_request         : []
+     type                : localnet
+     up                  : false
+
+
+As you can see, the two ``localnet`` ports are configured with a
+VLAN tag and are related to a single ``Logical_Switch`` entry. When
+*ovn-controller* sees that a port in that network has been bound to the
+node it's running on it will create a patch port to the provider bridge
+accordingly to the bridge mappings configuration.
+
+  .. code-block:: bash
+
+     compute-1: bridge-mappings = segment-1:br-provider1
+     compute-2: bridge-mappings = segment-2:br-provider2
+
+For example, when a port in the multisegment network gets bound to
+compute-1, ovn-controller will create a patch-port between br-int and
+br-provider1.
+
+An important note here is that, on a given hypervisor only ports belonging
+to **the same segment** should be present. **It is not allowed to mix
+ports from different segments on the same hypervisor for the same network
+(Logical_Switch).**

doc/source/ovn/gaps.rst

@@ -50,24 +50,16 @@ at [1]_.
   ports on a Chassis (a "node" in OVN terms) where the availability
   zones match with the router availability zones [6]_.
 
-* Routed provider networks
-
-  Routed provider networks allow for a single provider network to
-  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) [7]_.
-
 * QoS minimum bandwidth allocation in Placement API
 
   ML2/OVN integration with the Nova placement API to provide guaranteed
-  minimum bandwidth for ports [8]_.
+  minimum bandwidth for ports [7]_.
 
 * IPv6 Prefix Delegation
 
   Currently ML2/OVN doesn't implement IPv6 prefix delegation. OVN logical
-  routers have this capability implemented in [9]_ and we have an open RFE to
+  routers have this capability implemented in [8]_ and we have an open RFE to
-  fill this gap [10]_.
+  fill this gap [9]_.
 
 * East/West Fragmentation
 
@@ -85,7 +77,6 @@ References
 .. [4] 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://docs.openstack.org/neutron/latest/admin/config-az.html
-.. [7] https://bugs.launchpad.net/neutron/+bug/1865889
+.. [7] https://specs.openstack.org/openstack/neutron-specs/specs/rocky/minimum-bandwidth-allocation-placement-api.html
-.. [8] https://specs.openstack.org/openstack/neutron-specs/specs/rocky/minimum-bandwidth-allocation-placement-api.html
+.. [8] https://patchwork.ozlabs.org/project/openvswitch/patch/6aec0fb280f610a2083fbb6c61e251b1d237b21f.1576840560.git.lorenzo.bianconi@redhat.com/
-.. [9] https://patchwork.ozlabs.org/project/openvswitch/patch/6aec0fb280f610a2083fbb6c61e251b1d237b21f.1576840560.git.lorenzo.bianconi@redhat.com/
+.. [9] https://bugs.launchpad.net/neutron/+bug/1895972
-.. [10] https://bugs.launchpad.net/neutron/+bug/1895972