Skip to content

Network ‐ OVS Bridge Interface Health Check

Jump to bottom Edit New page
hoberger-rh edited this page Apr 23, 2026 · 10 revisions

Description

This rule checks if OVS bridge interfaces are properly configured on OVN-Kubernetes nodes. It validates bridges with physical ports, distinguishing between primary bridges and secondary network bridges.

Primary bridges must have an internal port (kernel interface), be in UP state, and have a link-local IP address (169.254.x.x). Secondary network bridges (configured for OVN localnet) only need to exist in OVS - they are pure L2 bridges and don't require internal ports or IP addresses.

The rule fails if any primary bridge is DOWN, missing, or lacks a link-local IP. Secondary bridges are identified from NodeNetworkConfigurationPolicy (NNCP) resources with OVN bridge-mappings.

Note: Integration bridges that only contain virtual/patch/internal ports are automatically excluded. Only bridges with physical ports or VLANs (external network connectivity) are validated.

Prerequisites

  • OpenShift cluster with OVN-Kubernetes networking
  • Open vSwitch installed and configured
  • OVS bridge created
  • Commands: ovs-vsctl, ip

Impact

OVS bridge issues cause complete network failure:

If Bridge is DOWN:

  • Total network loss - No traffic can flow through node
  • Node isolation - Node cannot communicate with cluster
  • All pods fail - Pod networking completely broken
  • Node NotReady state - Kubelet cannot reach API server
  • Cluster degradation - Workloads cannot schedule on affected node

If Bridge has No IP:

  • OVN not initialized - OVN controller hasn't configured networking
  • Pod network unavailable - Pods cannot get IP addresses
  • Inter-pod communication failure - No pod-to-pod connectivity
  • Service networking broken - Services unreachable

If Bridge has Wrong IP Subnet:

  • OVN datapath broken - Incorrect IP range for OVN operations
  • Routing failures - Traffic cannot be properly forwarded
  • Encapsulation errors - Geneve/VXLAN tunnels fail

Secondary network bridges are pure L2 bridges - missing internal ports or IPs is expected behavior and does not impact cluster operation.

Root Cause

Common scenarios causing bridge issues:

  • Bridge link down - OVS service stopped, bridge deleted or misconfigured, or NetworkManager connection inactive
  • Missing IP address - OVN controller not running, ovn-kubernetes pods not started, or network operator failure
  • Missing internal port (primary bridge) - NetworkManager failed to create internal port, OVS configuration incomplete, or NNCP policy error
  • Wrong IP subnet - Manual IP configuration on bridge or DHCP assigned non-link-local IP
  • OVS database corruption - Database file corrupted, bridge configuration lost, or OVS upgrade issues

Note: Secondary network bridges (configured for OVN localnet) intentionally lack internal ports and IPs - this is not a failure.

Diagnostics

Check OVS bridge status and configuration:

# List all OVS bridges
ovs-vsctl list-br

# List ports on each bridge
ovs-vsctl list-ports <bridge-name>

# Check which interfaces are hardware-backed (bridges with these are validated)
# Physical NICs (have device symlink - no output means no physical NICs):
ls -d /sys/class/net/*/device

# Bond interfaces (have bonding directory - no output means no bonds):
ls -d /sys/class/net/*/bonding

# Team interfaces (have team directory - no output means no teams):
ls -d /sys/class/net/*/team

# List all actual VLAN interfaces on the node
ls /proc/net/vlan/*

# Check if bridge is configured as secondary network (OVN localnet)
oc get nodenetworkconfigurationpolicies.nmstate.io -A -o yaml | grep -A 10 "name: <bridge-name>"

# Check bridge link state (replace <bridge-name> with your bridge, e.g., br-ex)
ip link show <bridge-name>

# Check bridge IP addressing (primary bridges should have 169.254.x.x link-local IP)
ip addr show <bridge-name>

# Check if bridge has internal port (primary bridges need this)
ovs-appctl dpif/show | grep -A 5 "<bridge-name>:"

Expected for primary bridges: Bridge interface exists, state is UP, has link-local IP (169.254.x.x), and has internal port in OVS datapath.

Expected for secondary bridges: Bridge exists in OVS with physical ports attached. Internal port and IP address are optional (pure L2 forwarding).

Resources

Add a custom footer
Add a custom sidebar

Clone this wiki locally