Simon Knight

Topology Generator

Active Rust Python

Contents

Concept

Rust-based network topology generator with Python bindings. Takes a declarative YAML config describing the desired topology type, scale, and parameters, and produces a validated network graph with realistic structure — proper tier hierarchies, vendor-specific interface naming, geographic placement, and bandwidth profiles.

Consolidates topology generation logic that was previously scattered across AutoNetKit, the Network Simulator, and the Network Visualization Engine into a single library. Network engineers can generate data center fabrics, WAN backbones, enterprise hierarchies, and random graph models without implementing the algorithms from scratch.

Three interfaces with parity guarantees: CLI for quick generation, Python API for workflow integration, config files for repeatable setups.

Technical Reports

Code Samples

README.md

# TopoGen Example Gallery

Curated config examples live under `examples/configs/`.
They are organized primarily by use case (directory) and are safe to copy/paste.

Each config starts with an annotated header block showing how to run it and which knobs to tweak.

## Quick start

```bash
topogen generate examples/configs/datacenter-lab/fat-tree--lab-k4-cisco--seed42.yaml --output topology.yaml
topogen validate topology.yaml

Examples (by use case)

datacenter-lab/

datacenter-scale/

regional-backbone/

global-backbone/

enterprise-wan/

modeling/

Python examples (by use case)

Runnable scripts live under examples/python/ and are organized by the same use-case directory names as the config gallery.

Notes:

datacenter-lab/

datacenter-scale/

regional-backbone/

global-backbone/

enterprise-wan/

modeling/

workflows/

parity/ (manual-only)

Topology type mapping

Use-case directories map back to roadmap topology types as follows:

Validation policy

By default, CI runs a smoke subset of example configs driven by examples/SMOKE.yaml.

Maintainers can run the full suite (including ignored tests) locally:

cargo test --test examples_configs -- --ignored

Python example validation is opt-in (to keep CI fast):

TOPOGEN_RUN_ALL_EXAMPLES=1 python -m pytest -q


### SMOKE.yaml

```yaml
# Authoritative smoke subset of example artifacts executed in CI by default.
#
# Paths are repo-relative.

configs:
  # Datacenter
  - examples/configs/datacenter-lab/fat-tree--lab-k4-cisco--seed42.yaml
  # Multi-layer
  - examples/configs/multi-layer-pop-backbone.yaml
  # WAN
  - examples/configs/regional-backbone/ring--na-8nodes-modern--seed42.yaml
  # Access ISP
  - examples/configs/access-isp/eyeball--regional-1k-subscribers--seed42.yaml
  # Random
  - examples/configs/modeling/barabasi-albert--scale-free-n100-m3--seed42.yaml
  - examples/configs/modeling/erdos-renyi--gnp-n50-p0.2--seed42.yaml

python:
  # Datacenter
  - examples/python/datacenter-lab/generate_fat_tree__k4_cisco_seed42.py
  - examples/python/datacenter-lab/generate_leaf_spine__2spine_4leaf_100g_seed42.py
  # WAN
  - examples/python/regional-backbone/generate_ring__na_8nodes_seed42.py
  - examples/python/global-backbone/generate_mesh__global_6nodes_seed42.py
  - examples/python/enterprise-wan/generate_hierarchical_wan__na_eu_20nodes_seed4242.py
  # Access ISP
  - examples/python/access-isp/generate_eyeball__regional_1k_seed42.py
  # Random
  - examples/python/modeling/generate_barabasi_albert__n100_m3_seed42.py
  - examples/python/modeling/generate_watts_strogatz__n100_k6_beta0.1_seed42.py
  - examples/python/modeling/generate_erdos_renyi__n50_p0.2_seed42.py
  # Workflow
  - examples/python/workflows/workflow_generate_export_restore_isomorphic.py
  - examples/python/workflows/workflow_multilayer_pop_to_containerlab.py
  - examples/python/workflows/workflow_eyeball_to_autonetkit.py

eyeball–regional-1k-subscribers–seed42.yaml

# Title: Eyeball access ISP (regional template, 1k subscribers)
# Goal: Access ISP hierarchy (access -> aggregation -> core) with peering/transit endpoints.
# Run:
#   topogen generate --config examples/configs/access-isp/eyeball--regional-1k-subscribers--seed42.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - subscriber_count: number of subscriber host nodes.
#   - template: small-isp|regional-isp|large-isp|mobile-network.
#   - tiers: 3|4.

name: eyeball-regional-1k
seed: 42

type: eyeball
template: regional-isp
subscriber_count: 1000
tiers: 3
redundancy: standard
peering_to_transit_split: 0.7

fat-tree–lab-k4-cisco–seed42.yaml

# Title: Fat-tree lab (k=4, Cisco interface names)
# Goal: Small, realistic datacenter topology for labs and demos.
# Run:
#   topogen generate examples/configs/datacenter-lab/fat-tree--lab-k4-cisco--seed42.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - k: even >= 2; controls size (pods and switch counts).
#   - vendor: cisco|arista|juniper|default (interface naming convention).
#   - core_bandwidth_gbps / agg_bandwidth_gbps: link bandwidths in Gbps.

name: dc-lab-fat-tree-k4-cisco
seed: 42
vendor: cisco

type: fat-tree
k: 4
core_bandwidth_gbps: 400.0
agg_bandwidth_gbps: 100.0

leaf-spine–lab-2spine-4leaf-100g–seed42.yaml

# Title: Leaf-spine lab (2 spines, 4 leaves, 100G)
# Goal: A compact 2-tier Clos for lab validation and quick iteration.
# Run:
#   topogen generate examples/configs/datacenter-lab/leaf-spine--lab-2spine-4leaf-100g--seed42.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - spines / leaves: scale the fabric size.
#   - spine_bandwidth_gbps: leaf<->spine bandwidth in Gbps.
#   - full_mesh: set false for partial connectivity experiments.

name: dc-lab-leaf-spine-2s-4l-100g
seed: 42

type: leaf-spine
spines: 2
leaves: 4
full_mesh: true
spine_bandwidth_gbps: 100.0

fat-tree–scale-k8–seed7.yaml

# Title: Fat-tree scale (k=8)
# Goal: Production-scale fat-tree to test larger fabrics and performance.
# Run:
#   topogen generate examples/configs/datacenter-scale/fat-tree--scale-k8--seed7.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - k: even >= 2; k=8 creates 80 switches.
#   - core_bandwidth_gbps / agg_bandwidth_gbps: link bandwidths in Gbps.

name: dc-scale-fat-tree-k8
seed: 7

type: fat-tree
k: 8
core_bandwidth_gbps: 400.0
agg_bandwidth_gbps: 400.0

leaf-spine–prod-4spine-16leaf-400g–seed99.yaml

# Title: Leaf-spine production (4 spines, 16 leaves, 400G)
# Goal: Modern, redundant spine layer with higher-speed fabric links.
# Run:
#   topogen generate examples/configs/datacenter-scale/leaf-spine--prod-4spine-16leaf-400g--seed99.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - spines / leaves: scale redundancy and rack count.
#   - spine_bandwidth_gbps: leaf<->spine bandwidth in Gbps.

name: dc-prod-leaf-spine-4s-16l-400g
seed: 99

type: leaf-spine
spines: 4
leaves: 16
full_mesh: true
spine_bandwidth_gbps: 400.0

hierarchical–na-eu-20nodes-variable-standard–seed4242.yaml

# Title: Enterprise WAN (hierarchical, NA+EU, 20 nodes)
# Goal: Multi-region 3-tier WAN (access/distribution/core) with realistic link profiles.
# Run:
#   topogen generate examples/configs/enterprise-wan/hierarchical--na-eu-20nodes-variable-standard--seed4242.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - node_count: total WAN sites/POPs.
#   - regions: which geo regions are included.
#   - bandwidth_profile: modern|variable.
#   - redundancy: minimal|standard|high.

name: enterprise-wan-na-eu-20
seed: 4242

type: hierarchical
node_count: 20
regions: ["NA", "EU"]
bandwidth_profile: variable
redundancy: standard

mesh–global-6nodes-tier1-modern–seed42.yaml

# Title: Global backbone mesh (6 nodes, Tier-1, modern)
# Goal: Small full-mesh backbone for CDN / Tier-1 interconnect experiments.
# Run:
#   topogen generate examples/configs/global-backbone/mesh--global-6nodes-tier1-modern--seed42.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - node_count: size of the mesh.
#   - city_tier: 1|2|3 (Tier-1 are major global hubs).
#   - bandwidth_profile: modern|variable.

name: wan-global-mesh-6-tier1-modern
seed: 42

type: mesh
node_count: 6
city_tier: 1
bandwidth_profile: modern

barabasi-albert–scale-free-n100-m3–seed42.yaml

# Title: Scale-free graph (Barabasi-Albert, n=100, m=3)
# Goal: Model a hub-heavy network with a power-law-ish degree distribution.
# Run:
#   topogen generate examples/configs/modeling/barabasi-albert--scale-free-n100-m3--seed42.yaml --output topology.yaml
#   topogen validate topology.yaml
# Tweak:
#   - n: number of nodes.
#   - m: new edges per node (higher m -> denser graph).

name: modeling-ba-n100-m3
seed: 42

type: barabasi-albert
n: 100
m: 3

Usage

Topology DSL Example

# Example: Multi-layer POP underlay with mesh overlay
name: multi-layer-pop-backbone
type: multi-layer

layers:
  - name: physical
    type: pop
    count: 5
    redundancy: n+1

  - name: backbone
    type: mesh
    node_count: 4
    underlay: physical
    strategy: shortest-path

Quick Facts

   
Status Active
Stack Rust, Python

What This Is

A Rust-based network topology generator with Python bindings that consolidates scattered topology generation logic from AutoNetKit, simulation tools, and visualization tools. Generates realistic data center, WAN, and random graph topologies with proper structure, design patterns, and realistic parameters. Outputs custom YAML format for use across the network engineering tool ecosystem.

Core Value

Network engineers can quickly generate realistic, validated network topologies without implementing complex algorithms from scratch.

Current Milestone: v1.5 - Intent-Based Overlays & Schematic Enrichment

Goal: Transform topologies from simple graphs into rich semantic models by formalizing intent-based “overlays” and hierarchical design patterns.

Target features:

Latest Release: v1.4 Interactive Editing & Incremental Validation (shipped 2026-03-02)

Next Milestone Goals

Requirements

# Validated

v1.0-alpha :

v0.9 :

v0.10 :

# Active

v1.1 Perf+Stability:

# Deferred / Tech Debt

# Out of Scope

Context

Consolidation: Topology generation code currently exists in three separate places:

This tool unifies that logic into a single, high-performance library.

Integration: Will likely become a dependency or part of the AutoNetKit workflow engine in the future. Designed to be the “whiteboard view” that other tools build from.

Architecture Model: Following AutoNetKit’s “whiteboard” concept - one graph with annotations where interfaces are stored under nodes in the YAML format rather than edge-centric representation. This is more extensible than classical graph interchange formats.

Users:

Inspirations:

Constraints

Key Decisions

Decision Rationale Outcome
Rust core + Python bindings Performance for large topology generation + cross-platform binary, while maintaining Python integration for existing tool ecosystem ✓ Good - PyO3 FFI works well, maturin build smooth
Custom YAML format for v1 Design ideal format for this use case, build converters to other formats (ContainerLab, AutoNetKit) later ✓ Good - Interface-centric model proved extensible
Interfaces under nodes (not edge-centric) Following AutoNetKit whiteboard model - more extensible than classical graph formats for network topologies with device types, interface naming, future BGP sessions/VPNs ✓ Good - More natural for network topology use cases
All three interfaces (CLI, Python API, config-driven) Maximum flexibility - engineers want CLI for quick generation, Python API for workflow integration, config files for complex/repeatable setups ✓ Good - Parity tests ensure consistency
Documentation-first for v0.9 Focus on making existing functionality discoverable rather than adding new features ✓ Good - mdBook + doc-tests prevent drift
InterfaceSpec source-of-truth Centralized parameter metadata prevents interface drift ✓ Good - Parity tests validate automatically

Ecosystem Context

This project is part of a seven-tool network automation ecosystem. topogen provides topology generation — the “generate” stage of the pipeline.

Role: Generate realistic, validated network topologies with vendor naming, geographic placement, and traffic matrices. Feed topologies into ank-pydantic (modeling), netsim (simulation), netflowsim (traffic analysis), and netvis (visualization).

Key integration points:

Architecture documents:

Last updated: 2026-02-21 after v1.1 milestone start