NetBox as Source of Truth
This document describes the role of NetBox as the authoritative source of truth for network design, addressing, and intent.
NetBox defines what the network is supposed to be. Configuration and monitoring exist to implement and verify that intent.
Design principles: see Lab Philosophy.
Purpose
NetBox is used to model and document:
- Physical network topology
- VLANs and IP address allocation
- Device roles and relationships
- Network intent and boundaries
It is not treated as a real-time state database or configuration engine.
Scope of Authority
NetBox is authoritative for the following domains:
Physical Infrastructure
- Routers, switches, and access points
- Device roles and locations
- Inter-device links and uplinks
- Port intent (access vs trunk)
Logical Design
- VLAN definitions and purpose
- IP prefixes and addressing plans
- Network segmentation boundaries
- Trust domain intent
Documentation Alignment
- Network documentation reflects NetBox-defined intent
- Changes to design flow through NetBox before implementation
- NetBox is treated as the canonical reference during troubleshooting
Explicit Non-Goals
NetBox is not used for:
- Real-time configuration state
- Live telemetry or metrics
- Automated remediation
- Dynamic control-plane decisions
Actual device configuration remains the responsibility of operators and configuration management tools.
Relationship to Configuration
The relationship between NetBox and device configuration is one-way:
NetBox (intent) ↓ Configuration (RouterOS, switch configs) ↓ Running network
Configuration drift is detected through review and monitoring, not prevented by NetBox itself.
Relationship to Monitoring
Monitoring consumes NetBox-defined intent to provide context:
- Expected VLANs vs observed traffic
- Intended uplinks vs link health
- Known dependencies vs failure events
Monitoring does not modify NetBox data.
Change Workflow
All significant network changes follow this order:
- Update NetBox to reflect intended design
- Review documentation impact
- Implement configuration changes
- Validate behavior via monitoring
This keeps design, documentation, and implementation aligned over time.
Current Status
NetBox adoption is in progress.
Initial focus areas include:
- Device inventory
- VLAN and IPAM modeling
- Physical link documentation
Automation and deeper integration will follow once the model stabilizes.
Design Notes
- NetBox encodes intent, not behavior
- Accuracy is prioritized over completeness
- Manual correctness precedes automation
- NetBox drives consistency, not speed
Related Documentation
- Switching & VLAN Fabric — Layer 2 topology and VLAN design
- Edge & Traffic Policy — WAN connectivity and routing
- Wireless — Access point deployment and RF design
This document applies to all current and future network infrastructure unless explicitly stated otherwise.