Technical Information

VMware vCenter to NetBox Object Mapping

Object Type Mapping Table

vCenter Object	NetBox Object	Key Attributes
Datacenter	ClusterGroup	name, description, tags
Cluster	Cluster	name, group (ClusterGroup), type "VMware vSphere", scope_site or scope_site_group, custom_fields.vcenter_cluster_moid
Host tag netbox_site:*	Site	name from tag value; default "DefaultSite"
Multi-site cluster	SiteGroup	name "SiteGroup-{cluster.name}"
ESXi Host	Device	name, manufacturer, device_type, serial, platform, status, site, cluster, custom_fields.vcenter_host_moid, custom_fields.vcenter_datacenter, custom_fields.vcenter_host_cpu_cores, custom_fields.vcenter_host_cpu_model, custom_fields.vcenter_host_memory_gb
Host hardware model	DeviceType	model, manufacturer
config.product.fullName	Platform	name (e.g. "VMware ESXi 7.0.0")
(static)	DeviceRole	name "ESXi Host"
Host vNIC / pNIC	Interface	name, primary_mac_address, type "other", enabled
Virtual Machine	VirtualMachine	name, status, vcpus, memory, cluster, site, custom_fields.vcenter_vm_uuid, custom_fields.vcenter_datacenter
(static)	DeviceRole	name "Virtual Machine"
config.guestFullName	Platform	name (guest OS full name)
VM network adapter	VMInterface	name, enabled, primary_mac_address, description, mtu
VM disk (FileBackingInfo)	VirtualDisk	name, size (MB), custom_fields.vcenter_datastore_name, custom_fields.vcenter_vmdk_path
Host vNIC IP / VM guest IP	IPAddress	address (CIDR), assigned to Interface or VMInterface
Interface / VM adapter MAC	MACAddress	mac_address (uppercase)
(static)	ClusterType	name "VMware vSphere"
summary.hardware.vendor	Manufacturer	name (per-host hardware vendor)

Field Mapping Details

Host Status Mapping

Host power_state in the integration is set only to "poweredOn" or "poweredOff" from runtime.powerState.

vCenter Power State	NetBox Status
poweredOn	active
poweredOff (or any other)	offline

VM Status Mapping

vCenter Power State	NetBox Status
poweredOn	active
poweredOff	offline
suspended	staged
Any other value	offline

Interface Type Mapping

vCenter Interface	NetBox Type
Host vNIC / pNIC	other
VM network adapter	virtual (VMInterface)

Site Discovery Logic

1. Tag-based: Host tags fetched via vCenter REST API (cis/tagging). First tag matching netbox_site:* gives site name (value after colon, trimmed).
2. Default: Hosts without such a tag are assigned to site "DefaultSite".
3. Sites created: One NetBox Site per unique site name discovered from tags; if none, a single Site "DefaultSite" is created.

Cluster Scoping Logic

Host site distribution	Cluster scope
All hosts in one site	scope_site (that site)
Hosts in multiple sites	New SiteGroup "SiteGroup-{cluster.name}" created; cluster uses scope_site_group; each child site gets custom_fields.parent_site_groups_json (JSON array referencing the SiteGroup).
No site info (all DefaultSite)	scope_site (DefaultSite)

Standalone hosts (ComputeResource but not ClusterComputeResource) are grouped into a synthetic cluster per datacenter: name \{datacenter}-StandaloneHostsCluster\.

IP Address Processing

• Host: vNIC spec.ip.ipAddress and spec.ip.subnetMask converted to CIDR (prefix length from mask); pNICs have no IPs.
• VM: From vm.guest.net[].ipConfig.ipAddress[]; subnetMask used for CIDR when present, else /32.
• Primary IP: First IPv4 and first IPv6 (by iteration order) on host or VM set as primary_ip4 / primary_ip6.

MTU Discovery (VM interfaces)

• Standard vSwitch: Host networkConfig.portgroup → vswitchName → networkInfo.vswitch → mtu.
• Distributed vSwitch: device.backing (DistributedVirtualPortBackingInfo) → host.configManager.dvsManager → switch by uuid → config.maxMtu.
• Fallback: None if not found.

Policy Configuration

• BOOTSTRAP (optional): When true, only static entities (custom fields, manufacturer) are created; no vCenter connection.
• VCENTER_HOST (required when not BOOTSTRAP): vCenter hostname or IP.
• VCENTER_USER (required when not BOOTSTRAP): Username for authentication.
• VCENTER_PWD (required when not BOOTSTRAP): Password for authentication.
• SKIP_SSL (optional): If true, SSL certificate validation is disabled for the vCenter connection.
• Scope – datacenters (optional): List of datacenter names to ingest; default all. Use ["*"] for wildcard. Invalid names cause validation to fail after fetching datacenters.

Connection uses pyVmomi SmartConnect with retry (3 attempts). Proxy support via HTTPS_PROXY/HTTP_PROXY.

Custom Fields

Custom Field	Object Type	Purpose
vcenter_vm_uuid	Virtual Machine	VM UUID from vCenter (config.uuid)
vcenter_datastore_name	Virtual Disk	Datastore name for the disk backing
vcenter_vmdk_path	Virtual Disk	VMDK file path (backing.fileName)
vcenter_host_moid	Device (ESXi host)	Host Managed Object ID (MOID)
vcenter_host_cpu_cores	Device (ESXi host)	Number of logical CPU cores on the host
vcenter_host_cpu_model	Device (ESXi host)	CPU model string from host hardware info
vcenter_host_memory_gb	Device (ESXi host)	Total host memory in gigabytes
vcenter_cluster_moid	Cluster	Cluster MOID when available
vcenter_datacenter	Device, Virtual Machine	Datacenter name containing the object
parent_site_groups_json	Site	JSON array of SiteGroup references; populated when a cluster spans multiple sites

Tags and Metadata

All created entities are tagged with:

• vmware
• vcenter
• discovered

Site names are derived from host tags (netbox_site:siteName); other tag values are not copied onto entities.

API and Behavior Notes

• APIs: pyVmomi (SOAP) for inventory and properties; vCenter REST API for tagging (cis/session, tagging/tag-association, tagging/tag/id).
• Data flow: Fetch datacenters and hosts (with tags) → fetch clusters and VMs → build ClusterGroups, Sites, ClusterType → build Clusters (with SiteGroups when multi-site) → build Hosts (devices, interfaces, IPs, MACs) → build VMs (interfaces, disks, IPs, MACs).
• Manufacturer: One manufacturer entity; set to "VMware" in bootstrap, then overwritten by each host's hardware.vendor during host build (typically same vendor across hosts).
• Entity order: Custom fields, manufacturer (bootstrap only), cluster_type, cluster_groups, site_groups, sites, clusters, devices, virtual_machines, interfaces, vm_interfaces, mac_addresses, ip_addresses, virtual_disks. DeviceType, DeviceRole, and Platform are not emitted as standalone entities; they are embedded in Device and VirtualMachine.