doc/networking: clarify how networking works

Make it clear that you need an uplink network and two dedicated network interfaces for MicroCloud. Signed-off-by: Ruth Fuchss <[email protected]>
canonical · Jan 10, 2024 · a72bbc1 · a72bbc1
1 parent b1171ec
commit a72bbc1
Show file tree

Hide file tree

Showing 5 changed files with 35 additions and 6 deletions.
diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt
@@ -10,7 +10,9 @@ DCO
 DHCP
 DNS
 GiB
+intra
 IOV
+IPs
 IPv
 LXD
 LXD's
@@ -21,6 +23,7 @@ MicroCloud's
 MicroOVN
 multicast
 OVN
+pre
 preseed
 rollout
 roadmap

diff --git a/doc/explanation/microcloud.rst b/doc/explanation/microcloud.rst
@@ -26,8 +26,33 @@ Networking
 
 By default, MicroCloud uses MicroOVN for networking, which is a minimal wrapper around OVN (Open Virtual Network).
 
-MicroOVN requires an uplink network that is an actual L2 subnet (which is usually not the case in a virtual cloud environment).
-In addition, MicroOVN requires its own dedicated network interface, for example, a dedicated physical network interface, a VLAN, or a virtual function on an :abbr:`SR-IOV (Single root I/O virtualisation)`-capable network interface.
+For external connectivity, MicroOVN requires an uplink network.
+This uplink network must support broadcast and multicast traffic (so that IP adverts and packets can flow between the OVN virtual router and the uplink network).
+Proper Ethernet networks generally fulfil these requirements, but virtual cloud environments often don't.
+
+Each machine in the MicroCloud cluster should have at least two available network interfaces (which can be connected to the same network or to different networks):
+
+.. _microcloud-networking-intracluster:
+
+Network interface for intra-cluster traffic
+  MicroCloud requires one network interface that is pre-configured with an IP address that is within the same subnet as the IPs of the other cluster members.
+  The network that it is connected to must support multicast.
+
+  This network interface can be, for example, a dedicated physical network interface, a VLAN, or a virtual function on an :abbr:`SR-IOV (Single root I/O virtualisation)`-capable network interface.
+  It serves as the dedicated network interface for MicroOVN and is used for multicast discovery (during setup) and all internal traffic between the MicroCloud, OVN, and Ceph members.
+
+.. _microcloud-networking-uplink:
+
+Network interface to connect to the uplink network
+  MicroCloud requires one network interface for connecting OVN to the uplink network.
+  This network interface must either be an unused interface that does not have an IP address configured, or a bridge.
+
+  MicroCloud configures this interface as an uplink interface that provides external connectivity to the MicroCloud cluster.
+
+  You can specify a different interface to be used as the uplink interface for each cluster member.
+  MicroCloud requires that all uplink interfaces are connected to the uplink network, using the gateway and IP address range information that you provide during the MicroCloud initialisation process.
+
+If you have a network interface that is configured as a Linux bridge, you can use it for both network interfaces.
 
 See :ref:`lxd:network-ovn` in the LXD documentation for more information.
 

diff --git a/doc/how-to/initialise.rst b/doc/how-to/initialise.rst
@@ -31,7 +31,7 @@ Complete the following steps to initialise MicroCloud:
 
      sudo microcloud init
 
-#. Select the IP address that you want to use for MicroCloud's internal traffic.
+#. Select the IP address that you want to use for MicroCloud's internal traffic (see :ref:`microcloud-networking-intracluster`).
    MicroCloud automatically detects the available addresses (IPv4 and IPv6) on the existing network interfaces and displays them in a table.
 
    You must select exactly one address.
@@ -75,7 +75,7 @@ Complete the following steps to initialise MicroCloud:
 
    If you choose ``yes``, configure the distributed networking:
 
-   1. Select the network interfaces that you want to use.
+   1. Select the network interfaces that you want to use (see :ref:`microcloud-networking-uplink`).
 
       You must select one network interface per machine.
    #. 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.

diff --git a/doc/reference/index.rst b/doc/reference/index.rst
@@ -33,7 +33,8 @@ Also see Ceph's :ref:`ceph:hardware-recommendations`.
 Networking requirements
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-For networking, MicroCloud requires a dedicated network interface and an uplink network that is an actual L2 subnet.
+For networking, MicroCloud requires two dedicated network interfaces: one for intra-cluster communication and one for external connectivity.
+To allow for external connectivity, MicroCloud requires an uplink network that supports broadcast and multicast.
 See :ref:`explanation-networking` for more information.
 
 The IP addresses of the machines must not change after installation, so DHCP is not supported.

diff --git a/doc/tutorial/get_started.rst b/doc/tutorial/get_started.rst
@@ -131,7 +131,7 @@ Complete the following steps to create the required disks in a LXD storage pool:
 3. Create a network
 -------------------
 
-MicroCloud requires an uplink network that the cluster members can use to communicate.
+MicroCloud requires an uplink network that the cluster members can use for external connectivity.
 See :ref:`explanation-networking` for more information.
 
 Complete the following steps to set up this network: