Technical Information

VMware vCenter to NetBox Object Mapping

This document provides a comprehensive mapping of VMware vCenter object types to their corresponding NetBox object types, based on the integration implementation.

Object Type Mapping Table

VMware vCenter Object	NetBox Object Type	Key Fields Mapped	Mapping Details
Datacenter	ClusterGroup	name → name
description
tags	One ClusterGroup per datacenter. Filtering via scope datacenters (default all).
Cluster	Cluster	name → name
datacenter → group (ClusterGroup)
hosts[] → scope
moid → custom_fields.vcenter_cluster_moid	Cluster type "VMware vSphere". Scope: single site → scope_site; multiple sites → new SiteGroup and scope_site_group. Standalone hosts → cluster named \{datacenter}-StandaloneHostsCluster\.
Site	Site	From host tag netbox_site:siteName → name
Default → "DefaultSite"	Sites discovered from host tags (REST API tagging). Unique site names from tags; if none, one site "DefaultSite".
SiteGroup	SiteGroup	name "SiteGroup-{cluster.name}"
description
Child sites linked via parent_site_groups	Created only when a cluster spans multiple sites (hosts in different netbox_site tags). Each child site gets parent_site_groups referencing this SiteGroup.
ESXi Host	Device	summary.config.name → name
summary.hardware.vendor → manufacturer
summary.hardware.model → device_type.model
hardware.systemInfo.serialNumber → serial
config.product.fullName → platform.name
runtime.powerState → status
Tag netbox_site:* → site
Cluster → cluster
moid → custom_fields.vcenter_host_moid
datacenter → custom_fields.vcenter_datacenter	Role "ESXi Host". Manufacturer overwritten per host from hardware.vendor (single manufacturer in collection). Primary IPv4/IPv6 set from first interface IPs.
Host Device Type	DeviceType	summary.hardware.model → model
manufacturer (from host vendor)	One device type per model.
Host Platform	Platform	config.product.fullName → name	ESXi product full name (e.g. "VMware ESXi 7.0.0").
Host Role	DeviceRole	Static "ESXi Host"	Single role for all hosts.
Host Interface	Interface	vNIC/pNIC device → name
spec.mac / pnic.mac → primary_mac_address (uppercase)
enabled True
type "other"	From networkConfig.vnic and networkInfo.pnic. IPs created as separate IPAddress entities (vNIC spec.ip → CIDR). Key: (host.name, interface.name).
Virtual Machine	VirtualMachine	name → name
config.uuid → custom_fields.vcenter_vm_uuid
runtime.powerState → status
config.hardware.numCPU → vcpus
config.hardware.memoryMB → memory
config.guestFullName → platform.name
cluster → cluster
Host's site → site
datacenter → custom_fields.vcenter_datacenter	Role "Virtual Machine". Primary IPv4/IPv6 from first VM interface IPs (guest.net).
VM Role	DeviceRole	Static "Virtual Machine"	Single role for all VMs.
VM Platform	Platform	config.guestFullName → name	Guest OS full name.
VM Interface	VMInterface	deviceInfo.label → name
connectable.connected → enabled
macAddress → primary_mac_address (uppercase)
deviceInfo.summary → description
Virtual switch MTU → mtu	MTU from standard vSwitch or DVS (get_virtual_switch_mtu). Key: (vm.name, deviceInfo.label).
Virtual Disk	VirtualDisk	deviceInfo.label → name
capacityInKB // 1024 → size (MB)
backing.datastore.name → custom_fields.vcenter_datastore_name
backing.fileName → custom_fields.vcenter_vmdk_path	Only FileBackingInfo disks; datastore/fileName as custom fields.
IP Address	IPAddress	Host: vNIC spec.ip.ipAddress + subnet → CIDR
VM: guest.net[].ipConfig.ipAddress[] + subnetMask → CIDR
Assigned to interface or vm_interface	Subnet mask converted to prefix length; default /32 if no mask.
MAC Address	MACAddress	macAddress / spec.mac → mac_address (uppercase)
Assigned to interface or vm_interface	One MAC entity per host or VM interface that has a MAC.
Cluster Type	ClusterType	Static "VMware vSphere"	Single cluster type for all clusters.
Manufacturer	Manufacturer	Initial "VMware"; then per host summary.hardware.vendor	build_manufacturer creates "VMware"; build_hosts overwrites with each host's vendor (single manufacturer retained).

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 parent_site_groups (object ref to 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_cluster_moid	Cluster	Cluster MOID when available
vcenter_datacenter	Device, Virtual Machine	Datacenter name containing the object
parent_site_groups	Site	Used when cluster spans multiple sites; links site to SiteGroup(s). Must exist in NetBox if multi-site clusters are used.

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.