IP ECMP Load Balancing

The following example configures an entry in a resilient-hash-prefix list. Active routes in the FIB that exactly match this prefix or are longer matches of this prefix are provided with resilient-hash programming. The hash-buckets-per-path value is 4 and the max-paths value is 6, so the fill pattern has 24 hash buckets, offering space for 6 next-hops, each repeated 4 times.

--{ +* candidate shared default }--[  ]--
# info with-context network-instance default ip-load-balancing resilient-hash-prefix *
    network-instance default {
        ip-load-balancing {
            resilient-hash-prefix 10.10.10.0/24 {
                hash-buckets-per-path 4
                max-paths 6
            }
        }
    }

Configure system options for dynamic load balancing

The following example configures system-level parameters to adjust the dynamic load balancing algorithm.

--{ +* candidate shared default }--[  ]--
# info with-context system load-balancing dynamic
    system {
        load-balancing {
            dynamic {
                flowset-size 512
                inactivity-timer 100
                link-quality-sampling-interval 7
                weighting-factor {
                    port-utilization 70
                    queue-utilization 20
                    itm-utilization 10
                }
            }
        }
    }

In this example, a flow must be inactive for a minimum of 100 microseconds to be moved to a better quality interface. The quality of the link is evaluated at an interval of 7 microseconds. The dynamic load balancing algorithm is configured so that port-utilization is weighted heaviest.

Configure the mode for dynamic load balancing

By default, dynamic load balancing assigns a flow to a different aggregate ECMP group if the flow is inactive following the initial assignment. You can optionally configure the mode for dynamic load balancing to either per-packet or flow-dynamic. In either mode, the system considers the port load quality and chooses the best quality path. In per-packet mode each packet is assigned to a best quality path. In flow-dynamic mode, the entire flow is assigned to a best quality path.

The following example sets the dynamic load balancing mode to per-packet.

--{ * candidate shared default }--[  ]--
# info with-context system load-balancing dynamic
    system {
        load-balancing {
            dynamic {
                mode per-packet
            }
        }
    }

Configure network prefixes for dynamic load balancing

Dynamic load balancing is enabled on an IP prefix-by-prefix basis within a network-instance. Routes matching the specified prefix have dynamic load balancing enabled on their associated ECMP next-hop group.

The following example enables dynamic load balancing for a prefix within the default network-instance.

--{ +* candidate shared default }--[  ]--
# info with-context network-instance default ip-load-balancing dynamic-load-balancing
    network-instance default {
        ip-load-balancing {
            dynamic-load-balancing {
                prefix 10.101.12.0/24 {
                }
            }
        }
    }

Configure resource monitoring thresholds for dynamic load balancing

The following example configures the system to generate a warning message when the usage level for dynamic load balancing ECMP groups exceeds a threshold, and a notice message when the usage level for dynamic load balancing ECMP groups drops below a threshold.

--{ +* candidate shared default }--[  ]--
# info with-context platform resource-monitoring datapath asic resource dynamic-load-balancing-ecmp-groups
    platform {
        resource-monitoring {
            datapath {
                asic {
                    resource dynamic-load-balancing-ecmp-groups {
                        upper-threshold-set 75
                        upper-threshold-clear 50
                    }
                }
            }
        }
    }

In this example, a warning message is generated and used-upper-threshold-exceeded of the datapath resource is set to true whenever utilization of the resource in any line card, forwarding complex, or pipeline reaches 75% in a rising direction. A notice message is generated and used-upper-threshold-exceeded is set to false whenever utilization of the datapath resource in any line card, forwarding complex, or pipeline reaches 50% in a falling direction.

Display resource usage for dynamic load balancing ECMP groups

The following example shows the current resource usage for dynamic load balancing ECMP groups in the system:

--{ running }--[  ]--
# info with-context from state platform linecard 1 forwarding-complex 0 datapath asic resource dynamic-load-balancing-ecmp-groups
    platform {
        linecard 1 {
            forwarding-complex 0 {
                datapath {
                    asic {
                        resource dynamic-load-balancing-ecmp-groups {
                            used-percent 100
                            used-entries 128
                            free-entries 0
                        }
                    }
                }
            }
        }
    }

Display the port quality for the ECMP path

The following example displays the current port quality metrics of the ECMP path. In this example, two metrics are displayed for each ITM. Single ITM platforms display a metric value of 0.

--{ running }--[  ]--
# info with-context from state interface ethernet-1/1 load-balancing
    interface ethernet-1/1 {
        load-balancing {
            last-dynamic-load-balancing-quality-metrics [
                7
                7
            ]
        }
    }

Verify that dynamic load balancing is enabled for a prefix

It is possible that dynamic load balancing may become disabled for a prefix because of exhaustion of resources such as flowset size or dynamic load balancing ECMP group limit. The following example displays whether dynamic load balancing is enabled for a prefix. In the example, dynamic-load-balancing true indicates the prefix is enabled for dynamic load balancing.

--{ running }--[  ]--
# info from state network-instance default route-table ipv4-unicast route 192.2.1.0/24 id 0 route-type static route-owner static_route_mgr origin-network-instance default
    leakable false
    leaked false
    metric 1
    preference 5
    active true
    last-app-update "2025-10-22T19:23:39.036Z (25 minutes ago)"
    next-hop-group 6181644
    next-hop-group-network-instance default
    resilient-hash false
    dynamic-load-balancing true
    fib-programming {
        suppressed false
        last-successful-operation-type add
        last-successful-operation-timestamp "2025-10-22T19:23:39.065Z (25 minutes ago)"
        pending-operation-type none
        last-failed-operation-type none
    }

In the following example, requested true indicates dynamic load balancing was configured for the prefix in the network-instance, and enabled true indicates that the prefix is programmed for dynamic load balancing. The flows-rebalanced statistic indicates the number of flows that were rebalanced from the original ECMP path assignment.

--{ + running }--[  ]--
# info from state network-instance default route-table next-hop-group 6181644
    backup-next-hop-group 0
    backup-active false
    dynamic-load-balancing {
        requested true
        enabled true
        flows-rebalanced 1290184