doc: Add documentation for OVN underlay configuration

Signed-off-by: Gabriel Mougard <[email protected]>

doc/explanation/microcloud.md

@@ -61,6 +61,19 @@ MicroCloud will still be usable, but you will see some limitations:
   As a result of this, network forwarding works at a basic level only, and external addresses must be forwarded to a specific cluster member and don't fail over.
 - There is no support for hardware acceleration, load balancers, or ACL functionality within the local network.
 
+(microcloud-networking-underlay)=
+
+Network interface to connect to an OVN underlay network
+:  While setting up the distributed networking with OVN, you can also decide to set up a dedicated underlay network for the OVN traffic.
+   A dedicated underlay network for OVN serves as the physical infrastructure over which the virtual networking (overlay network) is constructed. It can be beneficial to set up a dedicated underlay network for the following reasons:
+
+- A dedicated underlay network isolates the overlay network traffic from other types of traffic (such as management traffic).
+- By dedicating a physical network solely for the purpose of the virtual network overlay, network congestion can be reduced.
+- A dedicated underlay network can be tuned to provide predictable latency and bandwidth characteristics, which are crucial for the performance of latency-sensitive applications running over the OVN overlay.
+- A dedicated underlay can be designed to scale independently of other networks, which allows for more efficient scaling of the overlay network as the demand for virtual network resources increases.
+
+See {ref}`howto-ovn-underlay` for how to set up a dedicated OVN underlay network.
+
 ### Dedicated internal network for Ceph
 You can set up a dedicated network for Ceph to separate the internal Ceph traffic from the rest of the MicroCloud cluster traffic.
 

doc/how-to/index.md

@@ -10,6 +10,7 @@ Install MicroCloud </how-to/install>
 Manage the snaps </how-to/snaps>
 Initialise MicroCloud </how-to/initialise>
 Configure Ceph networking </how-to/ceph_networking>
+Configure OVN underlay </how-to/ovn_underlay>
 Add a machine </how-to/add_machine>
 Remove a machine </how-to/remove_machine>
 Add a service </how-to/add_service>

doc/how-to/initialise.md

@@ -90,6 +90,13 @@ Complete the following steps to initialise MicroCloud:
       You must select one network interface per machine.
    1. If you want to use IPv4, specify the IPv4 gateway on the uplink network (in CIDR notation) and the first and last IPv4 address in the range that you want to use with LXD.
    1. If you want to use IPv6, specify the IPv6 gateway on the uplink network (in CIDR notation).
+   1. If you chose to set up distributed networking, you can choose to setup an underlay network for the distributed networking:
+
+      If you choose ``yes``, configure the underlay network:
+
+      1. Select the network interfaces that you want to use (see {ref}`microcloud-networking-underlay`).
+
+         You must select one network interface with an IP address per machine.
 1. MicroCloud now starts to bootstrap the cluster.
    Monitor the output to see whether all steps complete successfully.
    See {ref}`bootstrapping-process` for more information.

doc/how-to/ovn_underlay.md

@@ -0,0 +1,83 @@
+(howto-ovn-underlay)=
+# How to configure an OVN underlay network
+
+When running {command}`microcloud init`, if you decided to setup distributed networking and if you have enough at least one unused network interface per cluster member with an IP address, you are asked if you want to configure an underlay network for OVN.
+Here is the question you will be asked:
+
+`Configure dedicated underlay networking? (yes/no) [default=no]: <answer>`
+
+You can choose to skip this question (just hit `Enter`). This will then use the internal MicroCloud network as an OVN 'underlay', which is the same as the OVN management network ('overlay' network).
+
+You could also choose to configure a dedicated underlay network for OVN with typing `yes`. A list of available network interfaces with an IP address will be displayed.
+You can then select one network interface per cluster member to be used as the interfaces for the underlay network of OVN.
+
+The following instructions build on the {ref}`get-started` tutorial and show how you can test setting up a MicroCloud with an OVN underlay network.
+
+1. Create the dedicated network for the OVN underlay:
+
+   1. First, create a dedicated network for the OVN cluster members to be used as an underlay. Let's call it `ovnbr0`:
+
+           lxc network create ovnbr0
+
+   1. Enter the following commands to find out the assigned IPv4 and IPv6 addresses for the networks and note them down:
+
+           lxc network get ovnbr0 ipv4.address
+           lxc network get ovnbr0 ipv6.address
+
+1. Create the network interfaces that will be used for the OVN underlay setup for each VM:
+
+   1. Add the network device for the `ovnbr0` network:
+
+           lxc config device add micro1 eth2 nic network=ovnbr0 name=eth2
+           lxc config device add micro2 eth2 nic network=ovnbr0 name=eth2
+           lxc config device add micro3 eth2 nic network=ovnbr0 name=eth2
+           lxc config device add micro4 eth2 nic network=ovnbr0 name=eth2
+
+1. Now, just like in the tutorial, start the VMs.
+1. On each VM, bring the network interfaces up and give them an IP address within their network subnet:
+
+   1. For the `ovnbr0` network, do the following for each VM::
+
+           # If the `ovnbr0` gateway address is `10.0.1.1/24` (subnet should be `10.0.1.0/24`)
+           ip link set enp7s0 up
+           # `X` should be a number between 2 and 254, different for each VM
+           ip addr add 10.0.1.X/24 dev enp7s0
+
+1. Now, you can start the MicroCloud initialisation process and provide the subnets you noted down when asked for the OVN underlay.
+1. We will use `ovnbr0` for the OVN underlay traffic. In a production setup, you'd choose the fast subnet for this traffic:
+
+           Configure dedicated underlay networking? (yes/no) [default=no]: yes
+           Select exactly one network interface from each cluster member:
+           Space to select; enter to confirm; type to filter results.
+           Up/down to move; right to select all; left to select none.
+                  +----------+--------+----------+-------------------------------------------+
+                  | LOCATION | IFACE  |   TYPE   |             IP ADDRESS (CIDR)             |
+                  +----------+--------+----------+-------------------------------------------+
+             [x]  | micro1   | enp7s0 | physical | 10.0.1.2/24                               |
+             [ ]  | micro1   | enp7s0 | physical | fd42:5782:5902:5b9e:216:3eff:fe01:67af/64 |
+             [x]  | micro3   | enp7s0 | physical | 10.0.1.4/24                               |
+             [ ]  | micro3   | enp7s0 | physical | fd42:5782:5902:5b9e:216:3eff:fe36:d29c/64 |
+           > [x]  | micro2   | enp7s0 | physical | 10.0.1.3/24                               |
+             [ ]  | micro2   | enp7s0 | physical | fd42:5782:5902:5b9e:216:3eff:fedb:f04e/64 |
+                  +----------+--------+----------+-------------------------------------------+
+
+1. The MicroCloud initialisation process will now continue as usual and the OVN cluster will be configured with the underlay network you provided.
+1. You can now inspect the OVN underlay setup:
+
+   1. Inspect the OVN southbound encapsulation parameters:
+
+     ```{terminal}
+       :input: microovn.ovn-sbctl --columns=ip,type find Encap type=geneve
+       :user: root
+       :host: micro1
+       :scroll:
+
+       ip                  : "10.77.55.2"
+       type                : geneve
+
+       ip                  : "10.77.55.4"
+       type                : geneve
+
+       ip                  : "10.77.55.3"
+       type                : geneve
+     ```

doc/tutorial/get_started.md

@@ -287,6 +287,8 @@ Complete the following steps:
       As we're setting up four machines only, the range must contain a minimum of four addresses, but setting up a bigger range is more fail-safe.
       For example, if your IPv4 gateway is `192.0.2.1/24`, the last address could be `192.0.2.254`.
    1. Specify the IPv6 address that you noted down for your `microbr0` network as the IPv6 gateway.
+   1. Leave the question empty for the DNS addresses for the distributed network.
+   1. Leave the question empty for configuring an underlay network for OVN.
 
 MicroCloud will now initialise the cluster.
 See {ref}`explanation-initialisation` for more information.
@@ -415,6 +417,7 @@ Specify the first IPv4 address in the range to use on the uplink network: 192.0.
 Specify the last IPv4 address in the range to use on the uplink network: 192.0.2.254
 Specify the IPv6 gateway (CIDR) on the uplink network (empty to skip IPv6): 2001:db8:d:200::1/64
 Specify the DNS addresses (comma-separated IPv4 / IPv6 addresses) for the distributed network (default: 192.0.2.1,2001:db8:d:200::1):
+Configure dedicated underlay networking? (yes/no) [default=no]:
 
 Initializing a new cluster
  Local MicroCloud is ready