OSDOCS-14356-New: Added bond best practices info to networking docs

dfitzmau · dfitzmau · commit 61c573705896 · 2025-11-24T09:47:42.000Z
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1748,6 +1748,8 @@ Topics:
     File: verifying-connectivity-endpoint
   - Name: Changing the cluster network MTU
     File: changing-cluster-network-mtu
+  - Name: Network bonding considerations
+    File: network-bonding-considerations
   - Name: Using Stream Control Transmission Protocol
     File: using-sctp
   - Name: Associating secondary interfaces metrics to network attachments
diff --git a/installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc b/installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc
@@ -38,9 +38,6 @@ include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset
 // Scale each machine set to compute nodes
 include::modules/creating-scaling-machine-sets-compute-nodes-networking.adoc[leveloffset=+2]
 
-// Enabling OVS balance-slb mode for your cluster
-include::modules/enabling-OVS-balance-slb-mode.adoc[leveloffset=+1]
-
 // Establishing communication between subnets
 include::modules/ipi-install-establishing-communication-between-subnets.adoc[leveloffset=+1]
 
diff --git a/installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc b/installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc
@@ -80,9 +80,6 @@ include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset
 // Scale each machine set to compute nodes
 include::modules/creating-scaling-machine-sets-compute-nodes-networking.adoc[leveloffset=+2]
 
-// Enabling OVS balance-slb mode for your cluster
-include::modules/enabling-OVS-balance-slb-mode.adoc[leveloffset=+1]
-
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_bare_metal/upi/installing-bare-metal.adoc b/installing/installing_bare_metal/upi/installing-bare-metal.adoc
@@ -101,9 +101,6 @@ include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset
 // Scale each machine set to compute nodes
 include::modules/creating-scaling-machine-sets-compute-nodes-networking.adoc[leveloffset=+2]
 
-// Enabling OVS balance-slb mode for your cluster
-include::modules/enabling-OVS-balance-slb-mode.adoc[leveloffset=+1]
-
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc b/installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc
@@ -95,9 +95,6 @@ include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset
 // Scale each machine set to compute nodes
 include::modules/creating-scaling-machine-sets-compute-nodes-networking.adoc[leveloffset=+2]
 
-// Enabling OVS balance-slb mode for your cluster
-include::modules/enabling-OVS-balance-slb-mode.adoc[leveloffset=+1]
-
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/modules/configuring-localnet-switched-topology.adoc b/modules/configuring-localnet-switched-topology.adoc
@@ -6,14 +6,9 @@
 [id="configuration-localnet-switched-topology_{context}"]
 = Configuration for a localnet switched topology
 
-// To accommodate a link to the NMstate Operator, the content in this module
-// is split with tags. The tag includes don't pull in the module header above.
-
-// tag::localnet-intro[]
+[role="_abstract"]
 The switched `localnet` topology interconnects the workloads created as Network Attachment Definitions (NADs) through a cluster-wide logical switch to a physical network.
-// end::localnet-intro[]
 
-// tag::localnet-content[]
 You must map a secondary network to the ovs-bridge to use it as an OVN-Kubernetes secondary network. Bridge mappings allow network traffic to reach the physical network. A bridge mapping associates a physical network name, also known as an interface label, to a bridge created with Open vSwitch (OVS).
 
 You can create an `NodeNetworkConfigurationPolicy` (NNCP) object, part of the `nmstate.io/v1` API group, to declaratively create the mapping. This API is provided by the NMState Operator. By using this API you can apply the bridge mapping to nodes that match your specified `nodeSelector` expression, such as `node-role.kubernetes.io/worker: ''`. With this declarative approach, the NMState Operator applies secondary network configuration to all nodes specified by the node selector automatically and transparently.
@@ -31,22 +26,25 @@ The `localnet1` network is mapped to the `br-ex` bridge in the following example
 apiVersion: nmstate.io/v1
 kind: NodeNetworkConfigurationPolicy
 metadata:
-  name: mapping <1>
+  name: mapping
 spec:
   nodeSelector:
-    node-role.kubernetes.io/worker: '' <2>
+    node-role.kubernetes.io/worker: ''
   desiredState:
     ovn:
       bridge-mappings:
-      - localnet: localnet1 <3>
-        bridge: br-ex <4>
-        state: present <5>
+      - localnet: localnet1
+        bridge: br-ex
+        state: present
 ----
-<1> The name for the configuration object.
-<2> A node selector that specifies the nodes to apply the node network configuration policy to.
-<3> The name for the secondary network from which traffic is forwarded to the OVS bridge. This secondary network must match the name of the `spec.config.name` field of the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes secondary network.
-<4> The name of the OVS bridge on the node. This value is required only if you specify `state: present`.
-<5> The state for the mapping. Must be either `present` to add the bridge or `absent` to remove the bridge. The default value is `present`.
++
+where:
++
+`metadata.name`:: The name for the configuration object.
+`node-role.kubernetes.io/worker::` A node selector that specifies the nodes to apply the node network configuration policy to.
+`localnet`:: The name for the secondary network from which traffic is forwarded to the OVS bridge. This secondary network must match the name of the `spec.config.name` field of the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes secondary network.
+`bridge` The name of the OVS bridge on the node. This value is required only if you specify `state: present`.
+`state`:: The state for the mapping. Must be either `present` to add the bridge or `absent` to remove the bridge. The default value is `present`.
 +
 The following JSON example configures a localnet secondary network that is named `localnet1`. Note that the value for the `mtu` parameter must match the MTU value that was set for the secondary network interface that is mapped to the `br-ex` bridge interface.
 +
@@ -74,13 +72,13 @@ In the following example, the `localnet2` network interface is attached to the `
 apiVersion: nmstate.io/v1
 kind: NodeNetworkConfigurationPolicy
 metadata:
-  name: ovs-br1-multiple-networks <1>
+  name: ovs-br1-multiple-networks
 spec:
   nodeSelector:
-    node-role.kubernetes.io/worker: '' <2>
+    node-role.kubernetes.io/worker: ''
   desiredState:
     interfaces:
-    - name: ovs-br1 <3>
+    - name: ovs-br1
       description: |-
         A dedicated OVS bridge with eth1 as a port
         allowing all VLANs and untagged traffic
@@ -90,23 +88,26 @@ spec:
         allow-extra-patch-ports: true
         options:
           stp: false
-          mcast-snooping-enable: true <4>
+          mcast-snooping-enable: true
         port:
-        - name: eth1 <5>
+        - name: eth1
     ovn:
       bridge-mappings:
-      - localnet: localnet2 <6>
-        bridge: ovs-br1 <7>
-        state: present <8>
+      - localnet: localnet2
+        bridge: ovs-br1
+        state: present
 ----
-<1> Specifies the name of the configuration object.
-<2> Specifies a node selector that identifies the nodes to which the node network configuration policy applies.
-<3> Specifies a new OVS bridge that operates separately from the default bridge used by OVN-Kubernetes for cluster traffic.
-<4> Specifies whether to enable multicast snooping. When enabled, multicast snooping prevents network devices from flooding multicast traffic to all network members. By default, an OVS bridge does not enable multicast snooping. The default value is `false`.
-<5> Specifies the network device on the host system to associate with the new OVS bridge.
-<6> Specifies the name of the secondary network that forwards traffic to the OVS bridge. This name must match the value of the `spec.config.name` field in the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes secondary network.
-<7> Specifies the name of the OVS bridge on the node. The value is required only when `state: present` is set.
-<8> Specifies the state of the mapping. Valid values are `present` to add the bridge or `absent` to remove the bridge. The default value is `present`.
++
+where:
++
+`metadata.name`:: Specifies the name of the configuration object.
+`node-role.kubernetes.io/worker`:: Specifies a node selector that identifies the nodes to which the node network configuration policy applies.
+`interfaces.name`:: Specifies a new OVS bridge that operates separately from the default bridge used by OVN-Kubernetes for cluster traffic.
+`mcast-snooping-enable`:: Specifies whether to enable multicast snooping. When enabled, multicast snooping prevents network devices from flooding multicast traffic to all network members. By default, an OVS bridge does not enable multicast snooping. The default value is `false`.
+`port.name`:: Specifies the network device on the host system to associate with the new OVS bridge.
+`localnet`:: Specifies the name of the secondary network that forwards traffic to the OVS bridge. This name must match the value of the `spec.config.name` field in the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes secondary network.
+`bridge`:: Specifies the name of the OVS bridge on the node. The value is required only when `state: present` is set.
+`state`:: Specifies the state of the mapping. Valid values are `present` to add the bridge or `absent` to remove the bridge. The default value is `present`.
 +
 The following JSON example configures a localnet secondary network that is named `localnet2`. Note that the value for the `mtu` parameter must match the MTU value that was set for the `eth1` secondary network interface.
 +
@@ -125,4 +126,3 @@ The following JSON example configures a localnet secondary network that is named
   "excludeSubnets": "10.100.200.0/29"
 }
 ----
-// end::localnet-content[]
diff --git a/modules/configuring-ovnk-use-second-ovs-bridge.adoc b/modules/configuring-ovnk-use-second-ovs-bridge.adoc
@@ -39,9 +39,9 @@ For more information about useful situations for the additional `br-ex1` bridge
 +
 [IMPORTANT]
 ====
-Do not use the Kubernetes NMState Operator to define or a `NodeNetworkConfigurationPolicy` (NNCP) manifest file to define the additional interface.
+Do not use the Kubernetes NMState Operator or a `NodeNetworkConfigurationPolicy` (NNCP) manifest file to define the additional interface. Ensure that the additional interface or sub-interfaces when defining a `bond` interface are not used by an existing `br-ex` OVN Kubernetes network deployment.
 
-Also ensure that the additional interface or sub-interfaces when defining a `bond` interface are not used by an existing `br-ex` OVN Kubernetes network deployment.
+As a postinstallation task, you cannot make configuration changes to the `br-ex` bridge or its underlying interfaces. As a workaround, use a secondary network interface connected to your host or switch.
 ====
 +
 .. Create the following interface definition files. These files get added to a machine configuration manifest file so that host nodes can access the definition files. 
diff --git a/modules/creating-manifest-file-customized-br-ex-bridge.adoc b/modules/creating-manifest-file-customized-br-ex-bridge.adoc
@@ -19,7 +19,14 @@ As an alternative to using the `configure-ovs.sh` shell script to set a `br-ex`
 endif::postinstall-bare-metal[]
 
 ifdef::postinstall-bare-metal[]
-As an alternative to using the `configure-ovs.sh` shell script to set a `br-ex` bridge on a bare-metal platform, you can create a `NodeNetworkConfigurationPolicy` (NNCP) custom resource (CR) that includes an NMState configuration file. The Kubernetes NMState Operator uses the NMState configuration file to create a customized `br-ex` bridge network configuration on each node in your cluster.
+As an alternative to using the `configure-ovs.sh` shell script to set a `br-ex` bridge on a bare-metal platform, you can create a `NodeNetworkConfigurationPolicy` (NNCP) custom resource (CR) that includes an NMState configuration file. 
+
+[NOTE]
+====
+As a postinstallation task, you cannot make configuration changes to the `br-ex` bridge or its underlying interfaces. As a workaround, use a secondary network interface connected to your host or switch.
+====
+
+The Kubernetes NMState Operator uses the NMState configuration file to create a customized `br-ex` bridge network configuration on each node in your cluster.
 
 [IMPORTANT]
 ====
diff --git a/modules/enabling-active-backup-mode.adoc b/modules/enabling-active-backup-mode.adoc
@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * networking/advanced_networking/network-bonding-considerations.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-active-backup-mode_{context}"]
+= Enabling active-backup mode for your cluster
+
+The `active-backup` mode provides fault tolerance for network connections by switching to a backup link where the primary link fails. The mode specifies the following ports for your cluster:
+
+* An active port where one physical interface sends and receives traffic at any given time.
+* A standby port where all other ports act as backup links and continously monitor their link status.
+
+During a failover process, if an active port or its link fails, the bonding logic switches all network traffic to a standby port. This standby port becomes the new active port. For failover to work, all ports in a bond must share the same Media Access Control (MAC) address. 
+
diff --git a/modules/installation-network-user-infra.adoc b/modules/installation-network-user-infra.adoc
@@ -89,17 +89,13 @@ During the initial boot, the machines require an IP address configuration that i
 
 [NOTE]
 ====
-* It is recommended to use a DHCP server for long-term management of the cluster machines. Ensure that the DHCP server is configured to provide persistent IP addresses, DNS server information, and hostnames to the cluster machines.
+* Consider using a DHCP server for long-term management of the cluster machines. Ensure that the DHCP server is configured to provide persistent IP addresses, DNS server information, and hostnames to the cluster machines.
 
 * If a DHCP service is not available for your user-provisioned infrastructure, you can instead provide the IP networking configuration and the address of the DNS server to the nodes at {op-system} install time. These can be passed as boot arguments if you are installing from an ISO image. See the _Installing {op-system} and starting the {product-title} bootstrap process_ section for more information about static IP provisioning and advanced networking options.
 ====
 endif::ibm-z[]
 
-The Kubernetes API server must be able to resolve the node names of the cluster
-machines. If the API servers and worker nodes are in different zones, you can
-configure a default DNS search zone to allow the API server to resolve the
-node names. Another supported approach is to always refer to hosts by their
-fully-qualified domain names in both the node objects and all DNS requests.
+The Kubernetes API server must be able to resolve the node names of the cluster machines. If the API servers and worker nodes are in different zones, you can configure a default DNS search zone to allow the API server to resolve the node names. Another supported approach is to always refer to hosts by their fully-qualified domain names in both the node objects and all DNS requests.
 endif::azure,gcp[]
 
 ifndef::ibm-z,azure[]
@@ -114,9 +110,7 @@ endif::ibm-z,azure[]
 [id="installation-network-connectivity-user-infra_{context}"]
 == Network connectivity requirements
 
-You must configure the network connectivity between machines to allow {product-title} cluster
-components to communicate. Each machine must be able to resolve the hostnames
-of all other machines in the cluster.
+You must configure the network connectivity between machines to allow {product-title} cluster components to communicate. Each machine must be able to resolve the hostnames of all other machines in the cluster.
 
 This section provides details about the ports that are required.
 
diff --git a/modules/installation-user-infra-machines-static-network.adoc b/modules/installation-user-infra-machines-static-network.adoc
@@ -220,7 +220,9 @@ ifndef::ibm-z-kvm[]
 
 === Bonding multiple network interfaces to a single interface
 
-Optional: You can bond multiple network interfaces to a single interface by using the `bond=` option. Refer to the following examples:
+As an optional configuration, you can bond multiple network interfaces to a single interface by using the `bond=` option. To apply this configuration to your cluster, complete the procedure steps for each node that runs on your cluster.
+
+.Procedure
 
 * The syntax for configuring a bonded interface is: `bond=<name>[:<network_interfaces>][:options]`
 +
@@ -229,26 +231,24 @@ and _options_ is a comma-separated list of bonding options. Enter `modinfo bondi
 
 * When you create a bonded interface using `bond=`, you must specify how the IP address is assigned and other
 information for the bonded interface.
-
++
 ** To configure the bonded interface to use DHCP, set the bond's IP address to `dhcp`. For example:
 +
 [source,terminal]
 ----
-bond=bond0:em1,em2:mode=active-backup
 ip=bond0:dhcp
 ----
-
++
 ** To configure the bonded interface to use a static IP address, enter the specific IP address you want and related information. For example:
 ifndef::ibm-z[]
 +
 [source,terminal]
 ----
-bond=bond0:em1,em2:mode=active-backup
 ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:bond0:none
 ----
 endif::ibm-z[]
 ifdef::ibm-z[]
-
++
 [source,terminal]
 ----
 bond=bond0:em1,em2:mode=active-backup,fail_over_mac=1
@@ -287,9 +287,9 @@ ifndef::ibm-z[]
 
 === Bonding multiple SR-IOV network interfaces to a dual port NIC interface
 
-Optional: You can bond multiple SR-IOV network interfaces to a dual port NIC interface by using the `bond=` option.
+As an optional configuration, you can bond multiple SR-IOV network interfaces to a dual port NIC interface by using the `bond=` option.
 
-On each node, you must perform the following tasks:
+.Procedure
 
 ifndef::installing-ibm-power[]
 . Create the SR-IOV virtual functions (VFs) following the guidance in link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_managing_virtualization/managing-virtual-devices_configuring-and-managing-virtualization#managing-sr-iov-devices_managing-virtual-devices[Managing SR-IOV devices]. Follow the procedure in the "Attaching SR-IOV networking devices to virtual machines" section.
@@ -308,12 +308,13 @@ The following examples illustrate the syntax you must use:
 
 * When you create a bonded interface using `bond=`, you must specify how the IP address is assigned and other information for the bonded interface.
 
-** To configure the bonded interface to use DHCP, set the bond's IP address to `dhcp`. For example:
+** To configure the bonded interface to use DHCP, set the `ip` parameter to `dhcp` as demonstrated in the following example:
 +
 [source,terminal]
 ----
 bond=bond0:eno1f0,eno2f0:mode=active-backup
 ip=bond0:dhcp
+fail_over_mac=0
 ----
 
 ** To configure the bonded interface to use a static IP address, enter the specific IP address you want and related information. For example:
diff --git a/modules/nw-kernel-bonding.adoc b/modules/nw-kernel-bonding.adoc
diff --git a/modules/nw-ovs-bonding.adoc b/modules/nw-ovs-bonding.adoc
diff --git a/modules/virt-example-nmstate-multiple-interfaces.adoc b/modules/virt-example-nmstate-multiple-interfaces.adoc
diff --git a/networking/advanced_networking/network-bonding-considerations.adoc b/networking/advanced_networking/network-bonding-considerations.adoc
diff --git a/networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator.adoc b/networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator.adoc

Original file line number	Diff line number	Diff line change
@@ -39,9 +39,9 @@ For more information about useful situations for the additional `br-ex1` bridge
`39`	`39`	`+`
`40`	`40`	`[IMPORTANT]`
`41`	`41`	`====`
`42`		-Do not use the Kubernetes NMState Operator to define or a `NodeNetworkConfigurationPolicy` (NNCP) manifest file to define the additional interface.
	`42`	+Do not use the Kubernetes NMState Operator or a `NodeNetworkConfigurationPolicy` (NNCP) manifest file to define the additional interface. Ensure that the additional interface or sub-interfaces when defining a `bond` interface are not used by an existing `br-ex` OVN Kubernetes network deployment.
`43`	`43`
`44`		-Also ensure that the additional interface or sub-interfaces when defining a `bond` interface are not used by an existing `br-ex` OVN Kubernetes network deployment.
	`44`	+As a postinstallation task, you cannot make configuration changes to the `br-ex` bridge or its underlying interfaces. As a workaround, use a secondary network interface connected to your host or switch.
`45`	`45`	`====`
`46`	`46`	`+`
`47`	`47`	`.. Create the following interface definition files. These files get added to a machine configuration manifest file so that host nodes can access the definition files.`