How vpatel95/topology-deployer works
Project Type and Purpose
• topology-deployer is a Python-based CLI tool for provisioning network topologies (networks and VMs) on an Ubuntu host.
• It reads a JSON config (from topologies/*.json or user‐supplied) and, via libvirt/QEMU (invoked through shell commands), creates or deletes networks and virtual machines.
Key Architectural Components
a. CLI & Entry Point
• deployer/deployer.py: parses command-line arguments, handles “create” vs “delete” operations, dispatches to network and VM flows.
• Packaging files (setup.py, pyproject.toml, requirements.txt, scripts/install) wrap the tool as a pip‐installable command (topology-deployer).
b. Topology Parser
• deployer/topology.py: loads and validates the JSON config (version, networks array, vms array).
c. Network Provisioner
• deployer/network.py: core routines to define and apply networks (management, NAT, isolated).
• deployer/nat_utils.py: handles NAT-specific setup (iptables rules, forwarding).
• Interacts with the Linux host networking stack (bridges, subnets).
d. VM Provisioner
• deployer/virtual_machine.py: defines and launches VMs using libvirt/QEMU command invocations.
• Configures flavors, vCPUs, RAM, disk, VNC ports, and attaches networks.
e. Shared Utilities & Globals
• deployer/utils.py, deployer/globals.py: logging setup, common constants, error handling.
f. Sample Configs & Topologies
• topologies/*.json: reference JSON network/VM definitions.
g. CI/CD & Testing
• .github/workflows/python-app.yml: test suite run on push/PR.
• .github/workflows/python-publish.yml: package publish pipeline.
• deployer/tests/: unit tests for deployer, network, VM modules.
Relationships & Data Flow
1. User invokes topology-deployer with flags and a JSON config.
2. CLI (deployer.py) calls Topology Parser → produces in-memory model.
3. For “create” operation:
a. Network Provisioner reads each network object → uses nat_utils for NAT networks → executes shell commands to create Linux bridges and network namespaces.
b. VM Provisioner reads each VM object → invokes QEMU/libvirt commands (via subprocess) to create disk images, define VMs, attach them to the previously created networks.
4. For “delete” operation: reverses the above steps.
5. Logging/verbosity flags control output; --dry-run prints commands instead of executing.
Architectural Patterns & Principles
• Modular design: clear separation between configuration parsing, network management, VM management, and utilities.
• Single Responsibility: each module handles one domain (networks vs VMs).
• Dependency injection via JSON: the entire topology is input-driven, making the tool data-centric and extensible.
• CLI–Library split: command parsing in deployer.py delegates to pure-python library code.
• Testing isolation: unit tests mock or simulate libvirt/network calls.