How bb-ricardo/netbox-sync works
Project type and purpose
• NetBox-Sync is a Python-based CLI tool that acts as a “Source of Truth” synchronizer.
• It connects to one or more external sources (VMware vCenter via pyvmomi and/or check_redfish inventory files), reads inventory data, and pushes updates into a NetBox instance via its REST API.
• It can run on demand, as a cron job, in Docker, or in Kubernetes.
File structure
• Top-level:
• netbox-sync.py: the CLI entry point
• Dockerfile / k8s-netbox-sync-cronjob.yaml: containerization/deployment
• settings-example.ini, config templates
• requirements*.txt
• module/ (the application code)
• common/: CLI parser, logging, misc utilities
• config/: all configuration parsing, multi‐format support (INI, YAML), option grouping, formatter
• netbox/: NetBox client, connection, object models, tagging/pruning logic
• sources/: source plugin pattern – each source type in its own subpackage
– vmware/: connection to vCenter, inventory extractor
– check_redfish/: parser for Redfish JSON inventory files
– common/: shared source logic (vlan handling, permitted subnets, abstraction base class)
• docs/: high-level concepts and per-source documentation
• scripts/: helper scripts (e.g., version bump, publishing)
Key insights from README
• Six‐step workflow: (1) parse config → (2) init sources + NetBox client → (3) fetch existing NetBox data → (4) fetch all source data → (5) sync/update NetBox → (6) prune orphans
• All operations driven by configuration (files or environment variables)
• Supports dry-run, log-level adjustments, multiple sources with override ordering
• Can tag objects in NetBox and remove stale resources after a grace period
a. Main components
• CLI Layer (netbox-sync.py, argparse)
• Configuration Loader (module/config/*)
• Core Orchestrator / Engine
• Source Plugins
– VMware Connector (module/sources/vmware)
– Redfish Connector (module/sources/check_redfish)
• NetBox Connector (module/netbox/connection.py + inventory models)
• Shared Services (module/common: logging, support utilities)
• External Systems
– VMware vCenter API
– check_redfish inventory files
– NetBox REST API
b. Relationships & data flow
1. User invokes CLI →
2. Config Loader reads settings (INI/YAML or env vars) →
3. Engine uses config to instantiate NetBox Connector + Source Plugin instances →
4. NetBox Connector fetches and caches current inventory →
5. Each Source Plugin fetches remote data (API calls or file parsing) →
6. Engine merges source data with current NetBox state, applies tag logic →
7. Engine issues create/update/delete calls via NetBox Connector →
8. Pruning module marks/removes orphans per policy
c. Architectural patterns
• Plugin architecture for sources (base class in module/sources/common/source_base.py)
• Separation of concerns: config parsing, connection management, orchestration, domain logic
• Idempotent sync pattern: read-modify-write + optional dry-run
• Tag-and-prune “lifecycle” pattern for garbage collection
d. Key technologies & libraries
• Python >=3.6
• argparse (CLI)
• requests, urllib3 (NetBox API)
• pyvmomi (vCenter SDK)
• aiodns (async DNS resolution)
• pyyaml, configparser (config files)
• Docker, Kubernetes (deployment)