leo-claude-mktplace/plugins/cmdb-assistant/skills/netbox-patterns/SKILL.md

description

description
NetBox best practices for data quality and consistency based on official NetBox Labs guidelines

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:

Object Type	Site Requirement
Devices	REQUIRED
Racks	REQUIRED
VMs	RECOMMENDED (via cluster or direct)
Clusters	RECOMMENDED
Prefixes	RECOMMENDED
VLANs	RECOMMENDED

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:

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:

• 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:

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:

• 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:

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:

• 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:

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

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