docs: ENIs should not be unmanaged by the OS

When ENIs are managed by services such as NetworkManager or systemd-networkd, it can happen that they interfere with Cilium's configuration. For example, systemd-networkd can remove the ENI IP assigned by Cilium if the carrier is temporarily down, thus breaking SNAT. We previously had a similar section regarding NetworkManager and DHCP in the EKS installation guide, but the EKS guide has since been replaced by the Cilium CLI installation guide. This section here therefore acts as a replacement and states that the devices need to be unmanaged (e.g. disabling DHCP is not enough for systemd-networkd). Signed-off-by: Sebastian Wicki <sebastian@isovalent.com>
cilium · Jun 8, 2021 · b15cee1 · b15cee1
1 parent 5b4fb53
commit b15cee1
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 0 deletions.
diff --git a/Documentation/concepts/networking/ipam/eni.rst b/Documentation/concepts/networking/ipam/eni.rst
@@ -459,3 +459,42 @@ Metrics
 *******
 
 The IPAM metrics are documented in the section :ref:`ipam_metrics`.
+
+******************
+Node Configuration
+******************
+
+The IP address and routes on ENIs attached to the instance will be
+managed by the Cilium agent. Therefore, any system service trying to manage
+newly attached network interfaces will interfere with Cilium's configuration.
+Common scenarios are ``NetworkManager`` or ``systemd-networkd`` automatically
+performing DHCP on these interfaces or removing Cilium's IP address when the
+carrier is temporarily lost. Be sure to disable these services or configure
+your Linux distribution to not manage the newly attached ENI devices.
+The following examples configure all Linux network devices named ``eth*``
+except ``eth0`` as unmanaged.
+
+.. tabs::
+
+   .. group-tab:: Network Manager
+
+        .. code-block:: shell-session
+
+            # cat <<EOF >/etc/NetworkManager/conf.d/99-unmanaged-devices.conf
+            [keyfile]
+            unmanaged-devices=interface-name:eth*,except:interface-name:eth0
+            EOF
+            # systemctl reload NetworkManager
+
+   .. group-tab:: systemd-networkd
+
+        .. code-block:: shell-session
+
+            # cat <<EOF >/etc/systemd/network/99-unmanaged-devices.network
+            [Match]
+            Name=eth[1-9]*
+
+            [Link]
+            Unmanaged=yes
+            EOF
+            # systemctl restart systemd-networkd
diff --git a/Documentation/spelling_wordlist.txt b/Documentation/spelling_wordlist.txt
@@ -614,6 +614,7 @@ netfilter
 netperf
 netsec
 netvsc
+networkd
 networkpolicy
 newproto
 newprotoparser