# Netbox Migration

> >

- **Type:** Skill
- **Install:** `agentstack add skill-netboxlabs-skills-netbox-migration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [netboxlabs](https://agentstack.voostack.com/s/netboxlabs)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [netboxlabs](https://github.com/netboxlabs)
- **Source:** https://github.com/netboxlabs/skills/tree/main/skills/netbox-migration

## Install

```sh
agentstack add skill-netboxlabs-skills-netbox-migration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:**
```python
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](https://github.com/netboxlabs)
- **Source:** [netboxlabs/skills](https://github.com/netboxlabs/skills)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-netboxlabs-skills-netbox-migration
- Seller: https://agentstack.voostack.com/s/netboxlabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.