Documenting Virtual Machines and Clusters in NetBox for Accurate Capacity Planning

Problem: Losing sight of where VMs run

When infrastructure grows, teams often lose track of which virtual machines reside on which physical hosts. Spreadsheets become stale, and capacity‑planning meetings rely on guesswork. NetBox’s Virtualization module solves this by letting you model Clusters, Hosts, and Virtual Machines as first‑class objects, preserving the physical‑to‑virtual relationship in a single source of truth.

Takeaway

By defining a Cluster, adding Hosts, and creating VMs linked to those Hosts, you gain a queryable inventory that can drive automation, reporting, and capacity decisions. The example below shows how to create a VM via the REST API and verify the link.

Modeling the hierarchy

NetBox treats a Cluster as a logical compute resource (e.g., a VMware cluster or a KVM host aggregate). Inside a Cluster you add one or more Host objects that represent the physical servers. A VirtualMachine is then assigned to a specific Host, which implicitly ties it to the parent Cluster.

Key fields you’ll set:

• Cluster: name, optional cluster group, and type (e.g., vmware or libvirt).
• Host: name, status, and the Cluster it belongs to.
• VirtualMachine: name, status, assigned Host, and resource allocations (vCPU, RAM, disk).

Worked example: Adding a VM through the API

Assume you have a NetBox instance reachable at https://netbox.example.com and an API token with write permission on the virtualization app. The following steps create a Cluster, a Host, and a VM.

1. Create a Cluster (run from any workstation with curl and the token exported as NETBOX_TOKEN):

   curl -s -X POST "https://netbox.example.com/api/virtualization/clusters/" \
     -H "Authorization: Token $NETBOX_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"prod‑vsphere‑cluster","cluster_group":null,"type":"vmware"}'
   

   Expected HTTP 201; note the returned id (e.g., 42).
2. Add a Host to that Cluster (replace CLUSTER_ID with the value from step 1):

   curl -s -X POST "https://netbox.example.com/api/virtualization/virtual-machines/" \
     -H "Authorization: Token $NETBOX_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"esxi01","status":"active","cluster":CLUSTER_ID}'
   

   Again, HTTP 201 returns the Host ID (e.g., 101).
3. Create a Virtual Machine assigned to the Host (replace HOST_ID):

   curl -s -X POST "https://netbox.example.com/api/virtualization/virtual-machines/" \
     -H "Authorization: Token $NETBOX_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"web01","status":"active","host":HOST_ID,"vcpus":4,"memory":8192,"disk":["40"]}'
   

   The response includes the VM’s ID and confirms the host field.

Where to run: Any machine with network access to the NetBox API and curl installed. No special privileges beyond the API token are required.

Risk: If the token lacks write scope, the calls will return 403. Double‑check the token’s permissions in NetBox’s user administration before proceeding.

Verifying the relationship

After creation, you can confirm the link via the API or the UI:

• API: GET https://netbox.example.com/api/virtualization/virtual-machines/?name=web01 returns a JSON object where host contains the Host’s name and cluster (via the Host) shows the Cluster name.
• UI: Navigate to Virtualization → Virtual Machines, find web01, and click the Host link to see its Cluster.

If the Host or Cluster fields are empty, the assignment failed—check the API response for validation errors.

Trade‑off and limitation

NetBox is a source of truth, not a monitoring system. It will not automatically detect when a VM is powered off, migrated, or deleted; you must feed those changes back through automation (e.g., a sync script that pulls from vCenter or libvirt). Over‑modeling every snapshot or temporary clone creates unnecessary rows, increasing database size and the risk of drift. A practical guardrail is to sync only persistent VMs and to prune retired records on a regular schedule (e.g., nightly job that deletes VMs with a retired status older than 30 days).

Actionable closing

Start small: define one Cluster that represents your most critical hypervisor farm, add its Hosts, and import the existing VMs via the API or CSV import. Use the returned IDs to build dashboards that show CPU and RAM allocation per Cluster, enabling data‑driven capacity planning. Periodically verify the sync by comparing the count of VMs in NetBox against the hypervisor’s inventory; any divergence signals a broken automation pipeline that needs attention.