# NetBox as Source of Truth

> This document describes the role of NetBox as the authoritative source of truth for network design, addressing, and intent.

Status: active · Kind: intent · Last verified: 2026-07-20 · Date: 2025-12-15

> Status: active
> Last verified: 2026-07-20 (against the current NetBox service and authority records)
> Scope: intended authority boundaries, not live inventory state

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](/homelab/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:

1. Update NetBox to reflect intended design
2. Review documentation impact
3. Implement configuration changes
4. 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](/homelab/network/switching-and-vlan-fabric) — Layer 2 topology and VLAN design
- [Edge & Traffic Policy](/homelab/network/edge-and-traffic-policy) — WAN connectivity and routing
- [Wireless](/homelab/network/wireless) — Access point deployment and RF design

---

This document applies to all current and future network infrastructure
unless explicitly stated otherwise.