NetBox Best Practices Skill

Reference documentation for proper NetBox data modeling, following official NetBox Labs guidelines.

CRITICAL: Dependency Order

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.

HIGH: Site Assignment

All infrastructure objects should have a site:

Why Sites Matter:

• •Location-based queries and filtering
• •Power and capacity budgeting
• •Physical inventory tracking
• •Compliance and audit requirements

HIGH: Tenant Usage

Use tenants for logical resource separation:

When to Use Tenants:

• •Multi-team environments (assign resources to teams)
• •Multi-customer scenarios (MSP, hosting)
• •Cost allocation requirements
• •Access control boundaries

Apply Tenants To:

• •Sites (who owns the physical location)
• •Devices (who operates the hardware)
• •VMs (who owns the workload)
• •Prefixes (who owns the IP space)
• •VLANs (who owns the network segment)

HIGH: Platform Tracking

Platforms track OS/runtime information for automation and lifecycle management.

Platform Examples:

Benefits:

• •Vulnerability tracking (CVE correlation)
• •Configuration management integration
• •Lifecycle management (EOL tracking)
• •Automation targeting

MEDIUM: Tag Conventions

Use tags for cross-cutting classification that spans object types.

Recommended Tag Patterns:

Tags vs Custom Fields:

• •Tags: Cross-object classification, multiple values, filtering
• •Custom Fields: Object-specific structured data, single values, reporting

MEDIUM: Naming Conventions

Consistent naming improves searchability and automation compatibility.

Recommended Patterns:

Avoid:

• •Inconsistent casing (mixing HotServ and hotserv)
• •Mixed separators (mixing hhl_cluster and media-cluster)
• •Generic names without context (server1, vm2)
• •Special characters other than hyphen

MEDIUM: Role Consolidation

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:

Docker Containers as VMs

NetBox's Virtualization module can model Docker containers:

Approach:

1. •Create device for physical Docker host
2. •Create cluster (type: "Docker Compose" or "Docker Swarm")
3. •Associate cluster with host device
4. •Create VMs for each container in the cluster

VM Fields for Containers:

• •name: Container name (e.g., media_jellyfin)
• •role: Container function (e.g., Media Server)
• •vcpus: CPU limit/shares
• •memory: Memory limit (MB)
• •disk: Volume size estimate
• •description: Container purpose
• •comments: Image, ports, volumes, dependencies

This is a pragmatic modeling choice - containers aren't VMs, but the Virtualization module is the closest fit for tracking container workloads.

Primary IP Workflow

To set a device/VM's primary IP:

1. •Create interface on device/VM
2. •Create IP address assigned to interface
3. •Set IP as primary_ip4 or primary_ip6 on device/VM

Why Primary IP Matters:

• •Used for device connectivity checks
• •Displayed in device list views
• •Used by automation tools (NAPALM, Ansible)
• •Required for many integrations

Data Quality Checklist

Before closing a sprint or audit:

• • All VMs have site assignment (direct or via cluster)
• • All VMs have tenant assignment
• • All active devices have platform
• • All active devices have primary IP
• • Naming follows conventions
• • No orphaned prefixes (allocated but unused)
• • Tags applied consistently
• • Clusters scoped to sites
• • Roles not overly fragmented

MCP Tool Reference

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