Skip to main content

ADR: NetBox Device Type Library Import Automation

Summary​

Automate NetBox device type imports from netbox-community/devicetype-library rather than maintaining manual device type definitions. All TheBurrow hardware exists in the community library. Import is idempotent and fully recoverable after a NetBox rebuild.

Status: Accepted Date: 2026-05-30 Implementation: mistborn-ops/netbox-tools

Context​

NetBox requires device type definitions before devices can be created. Device types encode manufacturer, model, interface counts, power specs, and form factor. TheBurrow has the following hardware requiring definitions:

  • Protectli Vault V1610 (nevermore)
  • Raspberry Pi 4B x5 (mistborn, fablehaven, hogwarts, locker9, conair)
  • Raspberry Pi 3B+ x1 (cosmere)
  • Buffalo LinkStation LS220D (the-archive)
  • TP-Link Deco M5 x3 (union-station, weasleyhallway, prefectbedroom)
  • AT&T BGW320-500 (The Veil)

All of these exist in the netbox-community/devicetype-library — the de facto standard community repository with 14,000+ device type definitions, actively maintained, and used by the majority of NetBox deployments globally.

Options Evaluated​

CategoryWeightOption A: AutomateOption B: Manual
Security posture54 — community repo via scoped API token; idempotent5 — no external dependency
Ops complexity44 — one script run, idempotent reruns2 — manual entry per type, error-prone
Reliability / maturity45 — de facto standard, 14k+ types3 — human error risk on interface counts
Ansible deployability45 — trivially scriptable via NetBox API1 — not automatable
Resource footprint35 — API calls only, no new service5 — same
Community / docs25 — actively maintained, well documented3 — NetBox docs cover manual entry

Weighted scores:

  • Option A (Automate): 101
  • Option B (Manual): 70

Decision​

Option A — Automate imports from netbox-community/devicetype-library.

Manual entry is error-prone for interface counts and specs, not repeatable, and not recoverable after a NetBox rebuild without re-entering everything by hand. The community library covers all TheBurrow hardware. Import is idempotent — running it again after a rebuild restores all device types without manual intervention.

The only meaningful argument for manual is no external dependency. Mitigated by: imports are read-only at run time, the API token used is scoped to device type writes only, and the library is cloned locally before import (no runtime internet dependency).

Implementation​

Tool​

netbox-community/devicetype-library provides a bundled import script (import.py) that reads YAML definitions and creates device types via the NetBox API. Runs as a one-shot script, not a persistent service.

Scope​

Import only the device types TheBurrow actually uses:

  • Protectli/V1610.yaml
  • Raspberry Pi/RPi-4B.yaml
  • Raspberry Pi/RPi-3B+.yaml
  • Buffalo/LS220D.yaml
  • TP-Link/Deco-M5.yaml
  • AT&T/BGW320-500.yaml

Token scope​

Dedicated read/write token scoped to device type objects only. Stored in Ansible Vault under vault_netbox_devicetype_token.

Execution​

Run manually on demand — initial population and after NetBox rebuild. Not scheduled. Device types change rarely.

Location​

Script and device type manifest live in mistborn-ops/netbox-tools.

Consequences​

Positive​

  • Device types match manufacturer specifications exactly
  • Fully recoverable after NetBox rebuild — re-run the script
  • No manual interface count entry — eliminates a common error source
  • Extensible — adding new hardware means adding one YAML path

Negative​

  • External dependency on netbox-community/devicetype-library at import time (mitigated by local clone)
  • Requires a dedicated API token with device type write scope

Alternatives Considered​

Manual entry only​

Rejected — not repeatable, not recoverable, error-prone for interface counts and power specs. Every NetBox rebuild requires re-entering all device types by hand.

  • mistborn-ops/ansible#95 — original decision issue
  • mistborn-ops/netbox-tools — implementation home
  • mistborn-ops/ansible#543 — topology population (uses device types)

Related Content​