Damien/fabric-orchestrator
1
0
Fork 0
Code Issues 16 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(netbox): Add NetBox API client with v4.4 compatibility #22

Merged
Damien merged 5 commits from feat/netbox-data-model into main 2026-01-09 14:26:03 +00:00
Conversation 0 Commits 5 Files Changed 5 +1406
Damien commented 2026-01-09 09:54:23 +00:00
Owner
Copy Link

Summary

This PR adds a comprehensive NetBox API client for retrieving fabric intent data, with full compatibility for NetBox 4.4.

Features

NetBox Client (src/netbox/client.py)

Device & Interface Methods

  • get_device, get_devices_by_role, get_leaf_devices, get_spine_devices
  • get_device_interfaces, get_device_loopbacks, get_device_lags, get_device_svis
  • get_interface_ips, get_device_ips

BGP Methods (netbox-bgp plugin)

  • get_bgp_sessions, get_bgp_peer_groups

L2VPN/EVPN Methods

  • get_l2vpns, get_l2vpn_terminations, get_vni_for_vlan

VRF Methods

  • get_vrfs, get_vrf, get_device_vrf_interfaces, get_route_targets, get_vrf_l3vni

MLAG Methods (Custom Fields)

  • get_device_mlag_config, get_mlag_peer_link, get_interface_mlag_id

Aggregated Intent

  • get_device_intent - Complete intent for a single device
  • get_fabric_intent - Complete intent for entire fabric

NetBox 4.4 API Compatibility Fixes

Issue Solution
ASN filter by device doesn't exist Read ASN from device custom field asn
L2VPN terminations can't filter by device Filter by l2vpn only, warn if device_name provided
Interfaces can't filter by VRF Query IPs with VRF filter, extract interface IDs
MLAG not natively supported Use custom fields on Device and Interface

Documentation

  • Complete data model documentation in docs/netbox-data-model.md
  • Custom fields reference with API creation examples
  • API filter compatibility notes (working vs non-working filters)
  • Relationship diagram showing NetBox model connections

Dependencies

  • pynetbox>=7.5.0 (tested with NetBox 4.4)

Custom Fields Required

Create these custom fields in NetBox before using the client:

Object Field Type Description
Device asn Integer BGP ASN
Device mlag_domain_id Text MLAG domain ID
Device mlag_peer_address Text MLAG peer IP
Device mlag_local_address Text MLAG local IP
Device mlag_virtual_mac Text Shared virtual MAC
Interface mlag_peer_link Boolean Marks MLAG peer-link
Interface mlag_id Integer MLAG port-channel ID
VRF l3vni Integer L3 VNI for symmetric IRB
VRF vrf_vlan Integer VLAN ID for L3 VNI SVI
IP Address virtual_ip Boolean Marks anycast/virtual IP

Testing

from src.netbox import FabricNetBoxClient

client = FabricNetBoxClient(url="https://netbox.example.com", token="xxx")

# Test basic retrieval
print(client.get_device("leaf1"))
print(client.get_device_asn("leaf1"))  # From custom field

# Test VRF interfaces (workaround)
print(client.get_device_vrf_interfaces("leaf1", "gold"))

# Test complete intent
intent = client.get_device_intent("leaf1")

Related

  • Relates to #5 (NetBox as Source of Truth)
  • Documentation: docs/netbox-data-model.md
## Summary This PR adds a comprehensive NetBox API client for retrieving fabric intent data, with full compatibility for NetBox 4.4. ## Features ### NetBox Client (`src/netbox/client.py`) **Device & Interface Methods** - `get_device`, `get_devices_by_role`, `get_leaf_devices`, `get_spine_devices` - `get_device_interfaces`, `get_device_loopbacks`, `get_device_lags`, `get_device_svis` - `get_interface_ips`, `get_device_ips` **BGP Methods (netbox-bgp plugin)** - `get_bgp_sessions`, `get_bgp_peer_groups` **L2VPN/EVPN Methods** - `get_l2vpns`, `get_l2vpn_terminations`, `get_vni_for_vlan` **VRF Methods** - `get_vrfs`, `get_vrf`, `get_device_vrf_interfaces`, `get_route_targets`, `get_vrf_l3vni` **MLAG Methods (Custom Fields)** - `get_device_mlag_config`, `get_mlag_peer_link`, `get_interface_mlag_id` **Aggregated Intent** - `get_device_intent` - Complete intent for a single device - `get_fabric_intent` - Complete intent for entire fabric ### NetBox 4.4 API Compatibility Fixes | Issue | Solution | |-------|----------| | ASN filter by device doesn't exist | Read ASN from device custom field `asn` | | L2VPN terminations can't filter by device | Filter by `l2vpn` only, warn if `device_name` provided | | Interfaces can't filter by VRF | Query IPs with VRF filter, extract interface IDs | | MLAG not natively supported | Use custom fields on Device and Interface | ### Documentation - Complete data model documentation in `docs/netbox-data-model.md` - Custom fields reference with API creation examples - API filter compatibility notes (working vs non-working filters) - Relationship diagram showing NetBox model connections ### Dependencies - `pynetbox>=7.5.0` (tested with NetBox 4.4) ## Custom Fields Required Create these custom fields in NetBox before using the client: | Object | Field | Type | Description | |--------|-------|------|-------------| | Device | `asn` | Integer | BGP ASN | | Device | `mlag_domain_id` | Text | MLAG domain ID | | Device | `mlag_peer_address` | Text | MLAG peer IP | | Device | `mlag_local_address` | Text | MLAG local IP | | Device | `mlag_virtual_mac` | Text | Shared virtual MAC | | Interface | `mlag_peer_link` | Boolean | Marks MLAG peer-link | | Interface | `mlag_id` | Integer | MLAG port-channel ID | | VRF | `l3vni` | Integer | L3 VNI for symmetric IRB | | VRF | `vrf_vlan` | Integer | VLAN ID for L3 VNI SVI | | IP Address | `virtual_ip` | Boolean | Marks anycast/virtual IP | ## Testing ```python from src.netbox import FabricNetBoxClient client = FabricNetBoxClient(url="https://netbox.example.com", token="xxx") # Test basic retrieval print(client.get_device("leaf1")) print(client.get_device_asn("leaf1")) # From custom field # Test VRF interfaces (workaround) print(client.get_device_vrf_interfaces("leaf1", "gold")) # Test complete intent intent = client.get_device_intent("leaf1") ``` ## Related - Relates to #5 (NetBox as Source of Truth) - Documentation: `docs/netbox-data-model.md`
Damien added 5 commits 2026-01-09 09:54:23 +00:00
docs: Add NetBox data model documentation for fabric intent 555f8436f1 
Documents how EVPN-VXLAN fabric configuration is represented in NetBox
using native models and the BGP plugin.

Includes:
- Model mapping tables (native + BGP plugin)
- IP addressing scheme
- BGP session configuration
- VXLAN/EVPN L2VPN setup
- MLAG custom fields requirements
- VRF configuration
- Data retrieval examples with pynetbox

Relates to #5
feat(netbox): Add NetBox API client for fabric intent retrieval 4799c4cbf2 
Implements FabricNetBoxClient using pynetbox to fetch:
- Device and interface data
- BGP sessions and peer groups (plugin)
- L2VPN/EVPN VNI mappings
- VRF and route target configuration
- MLAG custom fields

Relates to #5
chore: add missing newline and update dependencies b1c46686d2 
- Fix missing newline at end of __init__.py
- Add certifi and charset-normalizer packages to uv.lock
- Update lock file with HTTP-related dependencies
docs: add complete custom fields reference and API compatibility notes 2f828f43d6 
- Add comprehensive custom fields table for Device, Interface, VRF, and IP Address
- Include API examples for custom field creation
- Document working vs non-working API filters for NetBox 4.4
- Add workarounds for filters that don't exist (ASN by device, L2VPN terminations by device)
- Update VRF interface assignment to show IP-based VRF membership
- Add virtual_ip custom field for anycast gateway support
fix(netbox): adapt client for NetBox 4.4 API compatibility ac763aa376 
- Bump pynetbox dependency to >=7.5.0
- Change get_device_asn to read ASN from device custom field instead of
  filtering ASNs by device (unsupported in NetBox 4.4)
- Remove device_name filter from get_l2vpn_terminations as L2VPN
  terminations cannot be filtered by device in NetBox 4.4
- Refactor get_vrf_interfaces to query IP addresses with VRF filter and
  extract associated interfaces (VRF filtering on interfaces unsupported)
- Add get_interface_mlag_id method to read MLAG ID from interface
  custom field
Damien merged commit 528b65e4c0 into main 2026-01-09 14:26:03 +00:00
Damien deleted branch feat/netbox-data-model 2026-01-09 14:26:08 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
documentation
Documentation tasks
 phase-1-yang-discovery
Phase 1: YANG Path Discovery and Validation
 phase-2-minimal-reconciler
Phase 2: Minimal Reconciler (VLANs, VNIs)
 phase-3-full-fabric
Phase 3: Full Fabric Coverage (BGP, MLAG, VRFs)
 phase-4-event-driven
Phase 4: Event-Driven Automation and CLI
 research
Research and investigation tasks
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Damien
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Damien/fabric-orchestrator#22
Delete Branch "feat/netbox-data-model"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?