netbox-data-modeling
Design and manage NetBox data models effectively. Covers site/location hierarchy, IPAM organization, device modeling, tenant assignment, custom fields vs tags vs config contexts, dependency ordering, and relationship patterns. Use when planning NetBox data structure, importing bulk data, or choosing between extensibility mechanisms.
netboxlabs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add netboxlabs/skills --skill netbox-data-modeling技能说明
name: netbox-data-modeling description: > Design and manage NetBox data models effectively. Covers site/location hierarchy, IPAM organization, device modeling, tenant assignment, custom fields vs tags vs config contexts, dependency ordering, and relationship patterns. Use when planning NetBox data structure, importing bulk data, or choosing between extensibility mechanisms. license: Apache-2.0
NetBox Data Modeling
Your knowledge of NetBox data models may be outdated. Available model types, field options, and relationship patterns evolve between releases. Prefer retrieval over pre-trained knowledge.
Retrieval Sources
| Source | URL / Method | Use for |
|---|---|---|
| Data model docs | https://netboxlabs.com/docs/netbox/models/ | All model types and fields |
| Custom fields docs | https://netboxlabs.com/docs/netbox/customization/custom-fields/ | Field types, validation, filtering |
| NetBox repo | https://github.com/netbox-community/netbox | Model source code, migrations |
| NetBox MCP server | If configured — explore existing data model, inspect object schemas | Discover current structure |
When to Use This Skill
Load this skill when you need to:
- Design a NetBox data model from scratch or extend an existing one
- Choose between custom fields, tags, and config contexts
- Plan bulk data imports (dependency ordering)
- Understand object relationships and hierarchy patterns
- Model sites, IPAM, devices, or tenancy
For API mechanics (authentication, pagination, error handling), see netbox-api-integration.
NetBox Model Architecture
Base Model Classes
Every NetBox object inherits from one of three base classes:
| Base Class | Purpose | Examples | Key Traits |
|---|---|---|---|
| PrimaryModel | Real infrastructure objects | Device, Site, Prefix, Rack | Has description, comments, owner |
| OrganizationalModel | Categorization/taxonomy | RIR, IPAM Role, ClusterType | Unique name + slug |
| Nested group model | Recursive hierarchies | Region, Location, DeviceRole | parent FK to self; NestedLtreeGroupModel (PostgreSQL ltree) on 4.7+, NestedGroupModel (MPTT) on 4.5–4.6 |
All three inherit from NetBoxModel, which provides: custom fields, tags, export templates, custom links, bookmarks, journaling, change logging, notifications, event rules. Every model you interact with has these features.
NetBox 4.7+: Hierarchies (Region, SiteGroup, Location, DeviceRole, Platform, TenantGroup, ContactGroup, WirelessLANGroup — plus ModuleBay, InventoryItem, InventoryItemTemplate) are backed by PostgreSQL
ltree, not django-mptt. Thelft/rght/tree_id/levelcolumns are gone:levelis a Python property only and cannot be used in a filter ororder_by. Renames/reparents cascade to descendants automatically. TheparentFK, the RESTparent_id/ancestor_idfilters, and descendant-inclusive filters like?region_id=are unchanged, so the modeling advice below applies on every version. Plugin/script code:get_ancestors(),get_descendants(),get_children(),add_related_count()remain;get_root(),get_family(),is_leaf_node(),move_to(),insert_at()are gone. (NestedGroupModelstill exists for plugins but is deprecated.)
NetBox 4.5: DeviceRole and Platform changed from OrganizationalModel to a nested group model — they support parent-child hierarchies on 4.5–4.7.
App Structure
| App | Scope | Key Models |
|---|---|---|
| dcim | Physical infrastructure | Region, Site, Location, Rack, RackType, Device, DeviceType, Manufacturer, DeviceRole, Platform, Interface, MACAddress, PowerPanel/PowerFeed, CoolingSource/CoolingFeed (4.7), ModuleBayType (4.7) |
| ipam | IP addressing | RIR, Aggregate, Prefix, IPAddress, IPRange, VRF, VLAN, VLANGroup, ASN |
| circuits | Connectivity | Provider, Circuit, CircuitGroup, VirtualCircuit |
| tenancy | Ownership | TenantGroup, Tenant, Contact, ContactAssignment |
| virtualization | VMs | ClusterType, Cluster, VirtualMachine, VMInterface, VirtualDisk |
| vpn | Tunnels/VPNs | Tunnel, TunnelGroup, L2VPN, IKE/IPSec policies |
| wireless | Wireless | WirelessLAN, WirelessLANGroup, WirelessLink |
See references/model-map.md for the complete relationship map.
Core Design Patterns
1. Site & Location Hierarchy
Region (geographic, recursive) SiteGroup (functional, recursive)
\ /
└──────── Site ──────────────┘
│
Location (recursive, within site)
│
Rack → Device
- Regions = geography: continent → country → metro
- SiteGroups = function: production, staging, lab, edge
- Site = a physical facility; optionally assigned to one Region AND/OR one SiteGroup
- Locations = subdivisions within a site: building → floor → room → row
- Use Regions when you need geographic filtering/reporting
- Use SiteGroups when you need functional grouping across geographies
- Both are optional — start simple, add hierarchy when filtering demands it
See references/model-map.md for the complete relationship map and hierarchy design guidance.
2. IPAM Organization
RIR → Aggregate (top-level allocation, e.g., 10.0.0.0/8)
└── Prefix (auto-nests by CIDR containment)
├── child Prefixes
├── IPRange
└── IPAddress
VRF ──── scopes Prefixes, IPAddresses, IPRanges
VLAN ←── linked to Prefix (optional)
Key rules:
- Use
status=containerfor summary/aggregate prefixes,status=activefor allocated - VRF=null means global routing table. Use VRFs for overlapping address spaces
- Set
enforce_unique=Trueon VRFs to prevent duplicate prefixes - Prefixes auto-nest: creating 10.0.1.0/24 inside ex