Scale Planning and Topology Design

This guide focuses on designing network.json and integration strategy choices for stable performance at scale.

Core Design Principles

Keep hierarchy only as deep as operationally necessary.
Avoid concentrating too much traffic under one top-level parent.
Prefer predictable naming and stable parent relationships to reduce queue churn.
Validate topology changes in a maintenance window before broad rollout.

Strategy Selection by Scale

Use the simplest integration strategy that still meets operational needs:

flowchart TD
    A[Need hierarchy visibility/control?] -->|No| B[flat]
    A -->|Yes| C{Need site-level aggregation?}
    C -->|No| D[ap_only]
    C -->|Yes| E{Need full backhaul/path shaping?}
    E -->|No| F[ap_site]
    E -->|Yes| G[full]
    G --> H{Single-core saturation?}
    H -->|Yes| I[Use promote_to_root]
    H -->|No| J[Keep full strategy]

Strategy	Typical Scale Fit	Tradeoff
`flat`	Maximum performance, minimal hierarchy	Lowest topology visibility/aggregation
`ap_only`	Large AP-driven networks	Good performance, moderate visibility
`ap_site`	Medium to large site/AP networks	Better aggregation with moderate overhead
`full`	Networks requiring full path/backhaul representation	Highest control and highest CPU/memory cost

If full is required and you observe single-core saturation, use promote_to_root to distribute load.

Parent/Child Distribution Guidance

Design goals:

Keep top-level parents balanced in traffic and circuit count.
Avoid very deep branch chains unless they add real shaping value.
Keep sibling naming unique and stable (important for virtual-node promotion and operational clarity).

Warning signs:

One core persistently overloaded while others are mostly idle.
Frequent major queue rebuilds after small integration updates.
WebUI CPU Tree shows skewed distribution not explained by demand.

Virtual Nodes and Logical Grouping

Virtual nodes are useful for logical organization and aggregation views.

Use virtual nodes to improve operability and reporting structure.
Do not use virtual nodes as a substitute for physical topology clarity.
Validate for name collisions after promotion behavior.
For logical-to-physical promotion and CPU/binpacking flow, see Advanced Configuration Reference.

Queue/Classifier Guardrails

At high scale, queue/class identifier pressure can become real.

Monitor for urgent issues such as TC_U16_OVERFLOW.
If encountered, reduce topology complexity and/or increase queue parallelism where appropriate.
Reassess strategy depth (full -> ap_site/ap_only) when overflow risk appears.

See Troubleshooting for urgent-code response steps.

Rollout Checklist for Topology Changes

Export current network.json and ShapedDevices.csv backups.
Apply one topology change set at a time.
Run/observe lqos_scheduler and lqosd logs after each change.
Validate WebUI:
- CPU Tree / CPU Weights distribution
- Flow Globe/ASN/Tree behavior
- scheduler status and urgent issues
Keep a rollback copy of prior integration settings and topology files.

3.5 KiB Raw Blame History