BGP integration

.github/workflows/tests.yml

@@ -130,6 +130,7 @@ jobs:
           sudo snap set lxd daemon.group=adm
           sudo lxd init --auto
           snap list
+          sudo apt install -y linux-modules-extra-$(uname -r)
 
       - name: Run system tests
         run: .bats/bats-core/bin/bats tests/${{ matrix.test-file }}

.wokeignore

@@ -0,0 +1,4 @@
+# how-to page for BGP needs to contain word "MASTER" in a
+# code-block and this seems to be the only way to avoid woke
+# warnings
+how-to/bgp.rst

docs/.custom_wordlist.txt

@@ -1,6 +1,10 @@
+BFD
+BGP
 CLI
 ESM
+FRR
 Geneve
+IPv
 LTS
 LXD
 Livepatch
@@ -19,13 +23,16 @@ RTD
 Snapcraft
 TLS
 UI
+VRF
+VRFs
 VMs
 Virtualization
 YY
 appctl
 backport
 bugfixes
 codebase
+config
 datapaths
 devel
 downscaling

docs/explanation/bgp-redirect.rst

@@ -0,0 +1,121 @@
+========================
+OVN integration with BGP
+========================
+
+OVN enabled support for integration with BGP in version ``24.09`` as an
+experimental feature (`BGP redirect commit`_). It enables redirecting BGP
+(and BFD) traffic from Logical Router Port to a Logical Switch Port. The
+Logical Switch Port can be then bound to an OVS port that shows up as a real
+network interface in the system. By doing so, it enables any routing daemons
+to listen on this interface and effectively act as if the daemon was listening
+on the Logical Router Port. Benefits of this type of integration are that it
+enables hardware offloading, as well as running BGP in unnumbered mode.
+
+MicroOVN can automate a lot of the steps to configure the BGP integration. For
+more information on how to configure it, see:
+:doc:`How-To: Configure OVN BGP integration </how-to/bgp>`
+
+Route announcement and VRFs
+---------------------------
+
+The part that provides automatic leaking of OVN routes to the BGP daemon
+has not been made part of the released OVN yet. However, as an experimental
+feature, we are including an `OVN patch series`_ that is a candidate for this
+feature in the upstream OVN.
+
+With this patch applied, it's possible to instruct OVN to create a `Linux VRF`_
+, an separate routing table to which it will leak its own routes. These routes
+can be then picked up by BGP daemon and announced to its peers.
+
+What MicroOVN sets up
+---------------------
+
+To fully set up BGP redirecting, MicroOVN requires following:
+
+* one or more physical interfaces that provide connectivity to the external
+  networks
+* one free IPv4 address per external network that will be assigned to the
+  OVN router for external connectivity.
+* VRF table ID that the OVN will create and to which the internal routes will
+  be leaked.
+
+With these information provided, MicroOVN will then set up an OVN ``Logical
+Router`` that will act as a gateway to the external networks. This is going to
+be a "gateway router" with name ``lr-<hostname>-microovn``.
+
+Each of the provided interfaces will be plugged to its own OVS bridge and
+connected to a unique ``Logical Switch``. The bridge will be called
+``br-<interface_name>`` and the switch will be
+``ls-<hostname>-<interface_name>``. The ``Logical Router`` will then be
+connected to the ``Logical Switches`` via ports named
+``lrp-<hostname>-<interface_name>`` and assigned the provided free IPv4
+address. This will effectively give external connectivity to the router
+and vice versa.
+
+After the external connectivity is set up, MicroOVN will create ``Logical
+Switch Port`` named ``lsp-<hostname>-<interface_name>-bgp`` in each ``Logical
+Switch``. This is the logical port to which the BGP traffic will be redirected.
+It will be bound to an OVS port named ``<interface_name>-bgp`` that will show up
+in the host system.
+
+MicroOVN will then configure required OVN options:
+
+* ``requested-tnl-key`` set to the value of the VRF table on the ``Logical
+  Router``
+* ``maintain-vrf`` set to ``true`` on each external ``Logical Router Port``
+* ``redistribute-nat`` set to ``true`` on each external ``Logical Router
+  Port``
+* ``redistribute-lb-vips`` set to ``true`` on each external ``Logical Router
+  Port``
+* ``routing-protocols`` set to ``BGP,BFD`` on each external ``Logical Router
+  Port``
+* ``redistribute-lb-vips`` set to the name of the ``Logical Switch Port`` to
+  which the traffic will be redirected on each external ``Logical Router
+  Port``
+
+As a last step, the redirect interfaces will be moved to the created VRF and the
+feature is ready to be used.
+
+Bundled BGP daemon
+------------------
+
+MicroOVN comes bundled with `FRR suite`_ that implements BGP and BFD daemons.
+Once the BGP integration is enabled, it can be used to listen on the newly
+created interfaces in the VRF and form connections with neighbours on the
+external networks.
+
+Automatic daemon configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MicroOVN is capable of using FRR to automatically set up BGP daemons when then
+integration is enabled. If user provides ``asn`` config option when enabling
+BGP, MicroOVN will start daemons on each "BGP redirect" system interface it
+created. This is a very opinionated configuration that uses "BGP unnumbered"
+mode for automatic neighbour discovery. In effect it looks something like this:
+
+.. code-block:: none
+
+   !
+   router bgp <ASN> vrf <vrf_name>
+    # One neighbor declaration is added for each external connection
+    neighbor <bgp-redirect-iface-1> interface remote-as internal
+    neighbor <bgp-redirect-iface-2> interface remote-as internal
+    ...
+   exit
+   !
+
+FRR configuration persistence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Whenever MicroOVN changes FRR config, it persists current "running"
+configuration by copying it to "startup" configuration file.
+
+When user disables BGP integration, the current "startup" configuration
+file is backed up to ``frr.conf_<unix_timestamp>`` file and subsequently
+replaced with the default empty configuration.
+
+.. LINKS
+.. _BGP redirect commit: https://github.com/ovn-org/ovn/commit/370527673c2b35c1b79d90a4e5052177e593a699
+.. _OVN patch series: https://patchwork.ozlabs.org/project/ovn/patch/[email protected]/
+.. _Linux VRF: https://docs.kernel.org/networking/vrf.html
+.. _FRR suite: https://frrouting.org

docs/explanation/index.rst

@@ -9,4 +9,5 @@ topics related to ``OVN`` or ``OVS``.
 .. toctree::
    :maxdepth: 1
 
-   tracks-and-upgrades
+   tracks-and-upgrades
+   bgp-redirect

docs/how-to/bgp.rst

@@ -0,0 +1,132 @@
+=============================
+Configure OVN BGP integration
+=============================
+
+.. important::
+
+   **Experimental feature**: OVN BGP integration is currently an experimental
+   feature in both MicroOVN and upstream OVN. As such it is still undergoing
+   testing and is subject to changes or removal in the future.
+
+Configuration of the OVN integration with BGP is a single-command process in
+the MicroOVN, for more information about what's happening under the hood, see:
+:doc:`Explanation: OVN integration with BGP </explanation/bgp-redirect>`.
+
+Enable BGP integration
+----------------------
+
+In this example, we have a host connected to two external networks:
+
+* ``10.0.10.0/24`` via interface ``eth1``
+* ``10.0.20.0/24`` via interface ``eth2``
+
+We are going to need one free IPv4 address on each network to give to the
+OVN ``Logical Router``, in this example we will use the first available
+address. We will also need an unused VRF table number, in this example we will
+use ``10``. Final, and optional, thing we will use is an AS number, we will
+simply pick ``1``, and by providing it, we will let MicroOVN know that we want
+it to auto-configure BGP daemons with this ``ASN``.
+
+.. important::
+
+   Never use interface that provides actual host connectivity for the purpose
+   of OVN BGP integration. These interfaces will be assigned to the OVS bridge
+   and you will lose your connection to the host.
+
+To enable BGP integration run:
+
+.. code-block:: none
+
+   microovn enable bgp --config ext_connection=eth1:10.0.10.1/24,eth2:10.0.20.1/24 --config vrf=10 --config asn=1
+
+You will receive positive confirmation message in the CLI and the setup is
+done. We can also inspect the new interfaces that were created.
+
+.. code-block:: none
+
+   ip link
+
+The output will show that we have a new VRF device and BGP redirect ports for
+each network we specified:
+
+.. code-block:: none
+
+   <snipped preceding output>
+
+   20: ovnvrf10: <NOARP,MASTER,UP,LOWER_UP> mtu 65575 qdisc noqueue state UP mode DEFAULT group default qlen 1000
+       link/ether c2:c3:11:b9:30:5c brd ff:ff:ff:ff:ff:ff
+   21: eth1-bgp: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master ovnvrf10 state UNKNOWN mode DEFAULT group default qlen 1000
+       link/ether 02:48:5a:cf:f6:47 brd ff:ff:ff:ff:ff:ff
+   22: eth2-bgp: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master ovnvrf10 state UNKNOWN mode DEFAULT group default qlen 1000
+       link/ether 02:ee:23:d2:88:14 brd ff:ff:ff:ff:ff:ff
+
+   <snipped remaining output>
+
+And since we requested auto-configuration of BGP daemons, we can check the FRR configuration:
+
+.. code-block:: none
+
+   microovn.vtysh -c "sh run"
+
+Part of the output should show our new BGP instances:
+
+.. code-block:: none
+
+   !
+   router bgp 1 vrf ovnvrf10
+    neighbor eth1-bgp interface remote-as internal
+    neighbor eth2-bgp interface remote-as internal
+   !
+
+.. note::
+
+   Note that for then neighbour configuration, we are not using the names of
+   actual physical interfaces (e.g. ``eth1``), but the names of the interfaces
+   that were created for BGP redirect (e.g. ``eth1-bgp``)
+
+If there are BGP neighbours already running and configured on the external
+networks, you can validate that they successfully established connections:
+
+.. code-block:: none
+
+   microovn.vtysh -c "sh bgp vrf ovnvrf10 neighbors"
+
+There will be a lot of output, but for both BGP neighbours, there should be
+line indicating that the connection is in "Established" state. Snippet example:
+
+.. code-block:: none
+
+   BGP neighbor on eth1-bgp: fe80::216:3eff:fec8:8649, remote AS 1, local AS 1, internal link
+     Local Role: undefined
+     Remote Role: undefined
+   Hostname: bgp-peer
+     BGP version 4, remote router ID 10.75.224.199, local router ID 10.0.20.1
+     BGP state = Established, up for 00:38:14
+     Last read 00:00:14, Last write 00:00:14
+
+Manual BGP daemon configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In case that the automatic FRR configuration provided by MicroOVN does not
+suite your needs, you can just omit the ``--config asn=<ASN>`` option when
+enabling BGP. Without that option, MicroOVN won't attempt to do any
+configuration changes to the FRR and you can proceed with your own manual
+configuration.
+
+Disable BGP integration
+-----------------------
+
+To disable BGP integration, simply run:
+
+.. code-block:: none
+
+   microovn disable bgp
+
+This will remove all VRF tables, virtual interfaces, OVS bridges, Logical
+Switches and Logical Routers that were created when the integration was
+enabled.
+
+MicroOVN will also backup and reset FRR startup configuration. The current
+"startup" configuration file will be backed up in the same directory under name
+``frr.conf_<unix_timestamp>`` and then replaced with the default, empty,
+FRR configuration.

docs/how-to/index.rst

@@ -15,3 +15,4 @@ a basic understanding of OVN.
    major-upgrades
    ovn-underlay
    service-control
+   bgp

microovn/api/services/control.go

@@ -1,6 +1,7 @@
 package services
 
 import (
+	"encoding/json"
 	"errors"
 	"net/http"
 	"net/url"
@@ -37,7 +38,13 @@ func enableService(s state.State, r *http.Request) response.Response {
 		return response.InternalError(errors.New("Service does not exist"))
 	}
 
-	err = node.EnableService(r.Context(), s, requestedService)
+	var extraConfig types.ExtraServiceConfig
+	err = json.NewDecoder(r.Body).Decode(&extraConfig)
+	if err != nil {
+		logger.Errorf("Failed to decode request body: %s", err)
+		return response.BadRequest(errors.New("failed to decode request"))
+	}
+	err = node.EnableService(r.Context(), s, requestedService, &extraConfig)
 	if err != nil {
 		return response.InternalError(err)
 	}