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

dfitzmau · 2025-05-08T15:56:36Z

Checklist of items:

static DHCP requirements
fail_over_mac=1
Remove ip=bond0 kargs.

Version(s):
4.12+

Link to docs preview:

SME has approved this change.
QE has approved this change.

ocpdocs-previewbot · 2025-05-08T16:16:38Z

🤖 Tue Dec 02 17:17:59 - Prow CI generated the docs preview:
https://93160--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

modules/virt-example-nmstate-multiple-interfaces.adoc

dfitzmau · 2025-05-30T09:39:49Z

/retest

modules/installation-network-user-infra.adoc

modules/installation-user-infra-machines-static-network.adoc

bergerhoffer · 2025-10-20T15:26:39Z

The branch/enterprise-4.21 label has been added to this PR.

This is because your PR targets the main branch and is labeled for enterprise-4.20. And any PR going into main must also target the latest version branch (enterprise-4.21).

If the update in your PR does NOT apply to version 4.21 onward, please re-target this PR to go directly into the appropriate version branch or branches (enterprise-4.x) instead of main.

cybertron

Okay, after some more investigation into OVS bond configs I have a couple more comments.

modules/enabling-active-backup-mode.adoc

cybertron · 2025-11-06T20:24:54Z

modules/nw-ovs-bonding.adoc

+Consider the following architectural layout for OVS bridges that interact with OVS interfaces:
+
+* A network interface uses a bridge MAC address for managing protocol-level traffic and other administrative tasks, such as IP address assignment.
+* The physical MAC addresses of physical interfaces do not handle traffic.


Actually for OVS bonding I think my comment may be invalid. We don't clone the MAC address in those configs.

rbbratta · 2025-11-07T16:23:05Z

modules/enabling-OVS-balance-slb-mode.adoc

+Consider that an OVS bond with `balance-slb` mode enabled might experience issues if the bond forwards unknown unicast traffic from one physical network interface controller (NIC) into the phsycial network through another NIC. This situation can result in an Layer 2 loop, or _bridge loop_, that in turn causes _MAC flapping_. 
+
+MAC flapping causes the same MAC address to exist in many network locations for a period of time. For example, a remote switch does not learn the MAC address for the destination of a unicast packet and this causes the packet to exist on all links available on the SLB bond configuration. As a workaround for this issue, you can set the bond to `active-backup` mode during MAC address assignment and then switch the bond to use `balance-slb` mode.
+====


We can delete this.

Thanks. Deleted:

[NOTE]
====
Consider that an OVS bond with balance-slb mode enabled might experience issues if the bond forwards unknown unicast traffic from one physical network interface controller (NIC) into the phsycial network through another NIC. This situation can result in an Layer 2 loop, or bridge loop, that in turn causes MAC flapping.

MAC flapping causes the same MAC address to exist in many network locations for a period of time. For example, a remote switch does not learn the MAC address for the destination of a unicast packet and this causes the packet to exist on all links available on the SLB bond configuration. As a workaround for this issue, you can set the bond to active-backup mode during MAC address assignment and then switch the bond to use balance-slb mode.
====

rbbratta · 2025-11-07T16:27:11Z

modules/installation-user-infra-machines-static-network.adoc

 [source,terminal]
 ----
 bond=bond0:em1,em2:mode=active-backup
 ip=bond0:dhcp


this doesn't work. bond= with DHCP does not support MAC cloning, so primary slave fail and reboot will get new DHCP lease with secondary slave MAC.

We need to remove bond= kernel args.

Maybe there is an extra kwarg to set secondary slave MAC.

Removed:

bond=bond0:em1,em2:mode=active-backup

rbbratta · 2025-11-07T16:28:04Z

modules/installation-user-infra-machines-static-network.adoc

 [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


bond= with static IP kinda works, but it also doesn't support cloned-macs, but it doesn't necessarily matter for static IP.

Removed:

bond=bond0:em1,em2:mode=active-backup

cybertron

/lgtm

We'll probably end up tweaking and adding content here, but this is a good start.

cybertron · 2025-11-21T22:32:06Z

modules/configuring-localnet-switched-topology.adoc


+[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.


Not a blocker for this patch, but if we're going to include these notes everywhere an NNCP is mentioned, we might want to explicitly state that it is in relation to Kubernetes-NMState. It is possible to make some changes to the underlying interfaces via other methods.

cybertron · 2025-11-21T22:34:46Z

modules/configuring-ovnk-use-second-ovs-bridge.adoc

+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.


Again not specific to this patch, but in this context we should probably include br-ex1 as a do-not-touch interface. I don't think we need to mention it everywhere, but since this doc is discussion the secondary br-ex1 bridge it would be worth including here.

Added br-ex1 to the list two "The following list of interface names are reserved and you cannot use the names with NMstate configurations:" notes.

openshift-ci · 2025-11-24T09:47:49Z

New changes are detected. LGTM label has been removed.

openshift-ci · 2025-12-02T17:19:16Z

@dfitzmau: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

openshift-ci bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label May 8, 2025

dfitzmau force-pushed the OSDOCS-14356-new branch from 18241e1 to 8846ca5 Compare May 8, 2025 16:03

openshift-ci bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels May 8, 2025

dfitzmau force-pushed the OSDOCS-14356-new branch from 8846ca5 to d6452ad Compare May 8, 2025 16:06

ocpdocs-vale-bot reviewed May 8, 2025

View reviewed changes

modules/virt-example-nmstate-multiple-interfaces.adoc Outdated Show resolved Hide resolved

dfitzmau force-pushed the OSDOCS-14356-new branch 2 times, most recently from 3296fa2 to 318fd00 Compare May 9, 2025 08:21

dfitzmau added branch/enterprise-4.12 branch/enterprise-4.13 branch/enterprise-4.14 branch/enterprise-4.15 branch/enterprise-4.16 branch/enterprise-4.17 branch/enterprise-4.18 branch/enterprise-4.19 branch/enterprise-4.20 labels Jul 9, 2025

dfitzmau force-pushed the OSDOCS-14356-new branch from 318fd00 to 1b5443b Compare July 9, 2025 11:27

cybertron reviewed Jul 9, 2025

View reviewed changes

modules/installation-network-user-infra.adoc Outdated Show resolved Hide resolved

modules/installation-user-infra-machines-static-network.adoc Show resolved Hide resolved

modules/installation-user-infra-machines-static-network.adoc Outdated Show resolved Hide resolved

dfitzmau force-pushed the OSDOCS-14356-new branch from 1b5443b to 5b7d324 Compare August 11, 2025 11:12

openshift-ci bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Aug 11, 2025

dfitzmau force-pushed the OSDOCS-14356-new branch 6 times, most recently from 02430e1 to 58716d3 Compare August 11, 2025 12:54

dfitzmau force-pushed the OSDOCS-14356-new branch 6 times, most recently from 10a409f to f780fb6 Compare October 16, 2025 13:51

bergerhoffer added the branch/enterprise-4.21 label Oct 20, 2025

bergerhoffer added this to the Continuous Release milestone Oct 20, 2025

cybertron reviewed Nov 6, 2025

View reviewed changes

dfitzmau force-pushed the OSDOCS-14356-new branch 2 times, most recently from f57d4fc to 4bab646 Compare November 7, 2025 12:57

rbbratta reviewed Nov 7, 2025

View reviewed changes

dfitzmau force-pushed the OSDOCS-14356-new branch from 4bab646 to d70dd73 Compare November 10, 2025 09:18

dfitzmau force-pushed the OSDOCS-14356-new branch 2 times, most recently from 759b474 to bad17ba Compare November 20, 2025 11:10

cybertron reviewed Nov 21, 2025

View reviewed changes

openshift-ci bot assigned cybertron Nov 21, 2025

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Nov 21, 2025

dfitzmau force-pushed the OSDOCS-14356-new branch from bad17ba to 61c5737 Compare November 24, 2025 09:47

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Nov 24, 2025

dfitzmau force-pushed the OSDOCS-14356-new branch 3 times, most recently from 08e4444 to 9570f0b Compare November 24, 2025 11:54

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

2cfe455

dfitzmau force-pushed the OSDOCS-14356-new branch from 9570f0b to 2cfe455 Compare December 2, 2025 17:08

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

dfitzmau commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

dfitzmau commented May 30, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bergerhoffer commented Oct 20, 2025

Uh oh!

cybertron left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dfitzmau Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rbbratta Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dfitzmau Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cybertron left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci bot commented Nov 24, 2025

Uh oh!

openshift-ci bot commented Dec 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

dfitzmau commented May 8, 2025 •

edited

Loading

ocpdocs-previewbot commented May 8, 2025 •

edited

Loading

dfitzmau Nov 10, 2025 •

edited

Loading

rbbratta Nov 7, 2025 •

edited

Loading

dfitzmau Nov 10, 2025 •

edited

Loading