NetBox best practices for data quality and consistency based on official NetBox Labs guidelines
Provides NetBox data modeling guidance following official best practices and dependency order.
/plugin marketplace add l3ocho/mktpl-claude-datasaas/plugin install cmdb-assistant@mktpl-claude-datasaasThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Reference documentation for proper NetBox data modeling, following official NetBox Labs guidelines.
Objects must be created in this order due to foreign key dependencies. Creating objects out of order results in validation errors.
1. ORGANIZATION (no dependencies)
├── Tenant Groups
├── Tenants (optional: Tenant Group)
├── Regions
├── Site Groups
└── Tags
2. SITES AND LOCATIONS
├── Sites (optional: Region, Site Group, Tenant)
└── Locations (requires: Site, optional: parent Location)
3. DCIM PREREQUISITES
├── Manufacturers
├── Device Types (requires: Manufacturer)
├── Platforms
├── Device Roles
└── Rack Roles
4. RACKS
└── Racks (requires: Site, optional: Location, Rack Role, Tenant)
5. DEVICES
├── Devices (requires: Device Type, Role, Site; optional: Rack, Location)
└── Interfaces (requires: Device)
6. VIRTUALIZATION
├── Cluster Types
├── Cluster Groups
├── Clusters (requires: Cluster Type, optional: Site)
├── Virtual Machines (requires: Cluster OR Site)
└── VM Interfaces (requires: Virtual Machine)
7. IPAM
├── VRFs (optional: Tenant)
├── Prefixes (optional: VRF, Site, Tenant)
├── IP Addresses (optional: VRF, Tenant, Interface)
└── VLANs (optional: Site, Tenant)
8. CONNECTIONS (last)
└── Cables (requires: endpoints)
Key Rule: NEVER create a VM before its cluster exists. NEVER create a device before its site exists.
All infrastructure objects should have a site:
| Object Type | Site Requirement |
|---|---|
| Devices | REQUIRED |
| Racks | REQUIRED |
| VMs | RECOMMENDED (via cluster or direct) |
| Clusters | RECOMMENDED |
| Prefixes | RECOMMENDED |
| VLANs | RECOMMENDED |
Why Sites Matter:
Use tenants for logical resource separation:
When to Use Tenants:
Apply Tenants To:
Platforms track OS/runtime information for automation and lifecycle management.
Platform Examples:
| Device Type | Platform Examples |
|---|---|
| Servers | Ubuntu 24.04, Windows Server 2022, RHEL 9 |
| Network | Cisco IOS 17.x, Junos 23.x, Arista EOS |
| Raspberry Pi | Raspberry Pi OS (Bookworm), Ubuntu Server ARM |
| Containers | Docker Container (as runtime indicator) |
Benefits:
Use tags for cross-cutting classification that spans object types.
Recommended Tag Patterns:
| Pattern | Purpose | Examples |
|---|---|---|
env:* | Environment classification | env:production, env:staging, env:development |
app:* | Application grouping | app:web, app:database, app:monitoring |
team:* | Ownership | team:platform, team:infra, team:devops |
backup:* | Backup policy | backup:daily, backup:weekly, backup:none |
monitoring:* | Monitoring level | monitoring:critical, monitoring:standard |
Tags vs Custom Fields:
Consistent naming improves searchability and automation compatibility.
Recommended Patterns:
| Object Type | Pattern | Examples |
|---|---|---|
| Devices | {role}-{location}-{number} | web-dc1-01, db-cloud-02, fw-home-01 |
| VMs | {env}-{app}-{number} | prod-api-01, dev-worker-03 |
| Clusters | {site}-{type} | dc1-vmware, home-docker |
| Prefixes | Include purpose in description | "Production web tier /24" |
| VLANs | {site}-{function} | dc1-mgmt, home-iot |
Avoid:
HotServ and hotserv)hhl_cluster and media-cluster)server1, vm2)Avoid role fragmentation - use general roles with platform/tags for specificity.
Instead of:
nginx-web-server
apache-web-server
web-server-frontend
web-server-api
Use:
web-server (role) + platform (nginx/apache) + tags (frontend, api)
Recommended Role Categories:
| Category | Roles |
|---|---|
| Infrastructure | hypervisor, storage-server, network-device, firewall |
| Compute | application-server, database-server, web-server, api-server |
| Services | container-host, load-balancer, monitoring-server, backup-server |
| Development | development-workstation, ci-runner, build-server |
| Containers | reverse-proxy, database, cache, queue, worker |
NetBox's Virtualization module can model Docker containers:
Approach:
VM Fields for Containers:
name: Container name (e.g., media_jellyfin)role: Container function (e.g., Media Server)vcpus: CPU limit/sharesmemory: Memory limit (MB)disk: Volume size estimatedescription: Container purposecomments: Image, ports, volumes, dependenciesThis is a pragmatic modeling choice - containers aren't VMs, but the Virtualization module is the closest fit for tracking container workloads.
To set a device/VM's primary IP:
primary_ip4 or primary_ip6 on device/VMWhy Primary IP Matters:
Before closing a sprint or audit:
Dependency Order for Creation:
1. dcim_create_site
2. dcim_create_manufacturer
3. dcim_create_device_type
4. dcim_create_device_role
5. dcim_create_platform
6. dcim_create_device
7. virt_create_cluster_type
8. virt_create_cluster
9. virt_create_vm
10. dcim_create_interface / virt_create_vm_interface
11. ipam_create_ip_address
12. dcim_update_device (set primary_ip4)
Lookup Before Create: Always check if object exists before creating to avoid duplicates:
1. dcim_list_devices name=<hostname>
2. If exists, update; if not, create
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.