Netbox Migration

NetBox Migration

> Your knowledge of NetBox import mechanisms may be outdated. Available import methods, bulk operation limits, and Diode entity types evolve between releases. Prefer retrieval over pre-trained knowledge.

Retrieval Sources

| Source | URL / Method | Use for | |--------|-------------|---------| | NetBox REST API docs | https://netboxlabs.com/docs/netbox/integrations/rest-api/ | Bulk create/update endpoints | | Diode docs | https://netboxlabs.com/docs/diode/ | High-volume ingestion | | pynetbox repo | https://github.com/netbox-community/pynetbox | Python SDK for scripted imports | | NetBox MCP server | If configured — verify imported data landed correctly | Post-migration validation |

This skill teaches how to think about and execute data migrations into NetBox. It covers the full lifecycle: analyzing messy source data, cleaning it, choosing an import strategy, loading it in the right order, and verifying everything landed correctly.

This is NOT about NetBox version upgrades. This is about getting data from spreadsheets, legacy tools, or other CMDBs into NetBox for the first time (or re-importing).

When to Use This Skill

• Given a spreadsheet, CSV, or data dump to import into NetBox
• Migrating from another CMDB/IPAM (phpIPAM, Device42, RackTables, ServiceNow, InfoBlox)
• Planning a NetBox deployment and need to populate initial data
• Consolidating data from multiple sources into NetBox as source of truth

Quick-Start Decision Tree

How much data?

• &limit=N) over deep ?offset=` scans — offset slows linearly at high offsets. See [netbox-api-integration](../netbox-api-integration/SKILL.md).

For API patterns, see [netbox-api-integration](../netbox-api-integration/SKILL.md).

Phase 4: Validation

Three validation layers — all three are required for a complete migration.

Layer 1: Structural (NetBox accepted it)

• Object counts match source: devices, IPs, prefixes, sites, VLANs
• No import errors or skipped records
• Required fields populated on all objects

Layer 2: Relational (connections correct)

• Every device has correct site, device type, manufacturer, and role
• Every IP assigned to the correct interface on the correct device
• Primary IPs set on devices that should have them
• Rack positions match source layout
• VLAN-to-prefix associations correct
• VRF assignments match routing design
• Prefix hierarchy makes sense (containers contain child prefixes)

Layer 3: Operational (matches live network)

• Devices in NetBox respond on the network
• IPs in NetBox match actual device configurations
• No devices on network missing from NetBox
• Interface states match reality
• This layer uses Discovery and Assurance — see Phase 5

See [references/validation-checklist.md](references/validation-checklist.md) for the complete checklist.

Validation script pattern:

import pynetbox
nb = pynetbox.api("https://netbox.example.com", token="...")

# Count verification
source_device_count = 500  # from your source data
assert nb.dcim.devices.count() >= source_device_count

# Spot-check critical devices
for name in ["core-rtr-01", "fw-01", "dns-01"]:
    d = nb.dcim.devices.get(name=name)
    assert d, f"Missing: {name}"
    assert d.primary_ip, f"No primary IP: {name}"
    assert d.site, f"No site: {name}"

# Find orphaned IPs
for ip in nb.ipam.ip_addresses.all():
    if not ip.assigned_object:
        print(f"Unassigned: {ip.address}")

Phase 5: Post-Migration

Migration isn't done when the data is loaded. It's done when NetBox matches reality and is established as the source of truth.

Run Discovery to fill gaps

Spreadsheets never have everything. Use the Orb Agent to discover what's missing:

• Network scanning (NMAP) — Find IPs not in NetBox, identify rogue devices
• Device discovery (NAPALM/SNMP) — Pull real interface configs, VLANs, MAC addresses, OS versions
• LLDP/CDP neighbor data — Discover cable connections automatically

Discovery fills the gaps that source data always has: interfaces, actual IP assignments, MAC addresses, real platform versions, cable topology. See [netbox-discovery](../netbox-discovery/SKILL.md).

Run Assurance to verify correctness

Define rules for what "correct" looks like, then check compliance:

• Every active device has a primary IP
• Every active device has at least one interface
• Every rack has a site and location
• Every prefix has a VRF (if multi-VRF environment)
• No duplicate IPs in the same VRF

See [netbox-assurance](../netbox-assurance/SKILL.md).

Establish ongoing processes

• Schedule regular Discovery runs to detect drift
• Review Assurance reports weekly
• Establish change process: changes go to NetBox first, then implement on network
• Integrate with automation (Ansible/Terraform pull from NetBox as source of truth)

Completeness Criteria

A migration is done when:

1. ✅ All source data is represented in NetBox (every device, IP, prefix, VLAN)
2. ✅ Relationships are correct (IPs → interfaces → devices → racks → sites)
3. ✅ Hierarchy is structured (regions → sites → locations → racks)
4. ✅ IPAM is organized (prefix hierarchy, VRF scoping, aggregates cover all space)
5. ✅ Naming is consistent (one convention, no duplicates, no ambiguity)
6. ✅ Discovery confirms reality matches (no phantom devices, no missing devices)
7. ✅ Assurance rules pass (compliance checks green)
8. ✅ Source system can be decommissioned (NetBox is now authoritative)

Anti-Patterns

1. Export ≠ import format — NetBox CSV export headers differ from import headers. Always test with a sample.
2. Case sensitivity — "Site A" and "site a" create duplicates, especially via Diode.
3. Interfaces auto-created — DeviceType templates create interfaces when a device is created. Don't re-create them.
4. Circular dependency (primary IP) — Requires two-pass: create device → create IP → assign back.
5. CSV encoding — Use UTF-8 without BOM, LF line endings.
6. Slug conflicts — Auto-generated slugs may collide. Provide explicit slugs when names are similar.
7. Device name uniqueness — Per site+tenant, not globally. Same name in different sites is fine.
8. Large CSV imports are slow — For > 1K objects, switch to API or Diode.
9. Don't migrate everything at once — Phase it. Sites → devices → IPAM → connections.
10. "Feeling overwhelmed" — Normal. Focus on what NetBox has models for. Ignore data that doesn't map.

References

• [references/source-mapping.md](references/source-mapping.md) — Field mappings by source system
• [references/dependency-order.md](references/dependency-order.md) — Complete 11-tier import order
• [references/validation-checklist.md](references/validation-checklist.md) — Post-import verification checklist
• [references/import-patterns.md](references/import-patterns.md) — Code examples for each import strategy

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: netboxlabs
• Source: netboxlabs/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.