Skip to main content
CloudEnterprise

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 ObjectNetBox Object TypeKey Fields MappedMapping Details
DatacenterClusterGroupnamenameMaps vCenter datacenter names to NetBox cluster groups for organizational hierarchy.
ClusterClusternamename
datacenter.namegroup
hosts[]scope_site or scope_site_groupMaps vCenter clusters to NetBox clusters, scoped to sites or site groups based on host distribution.
ESXi HostDevicesummary.config.namename
summary.hardware.vendormanufacturer.name
summary.hardware.modeldevice_type.model
hardware.systemInfo.serialNumberserial
config.product.fullNameplatform.name
runtime.powerStatestatus
site_name (from tags) → siteMaps host hardware details, platform information, and operational status. Site assignment based on netbox_site: tags or defaults to "DefaultSite".
Host Device TypeDeviceTypesummary.hardware.modelmodel
summary.hardware.vendormanufacturerCreates device types based on host hardware model and vendor information.
Host PlatformPlatformconfig.product.fullNamenameMaps ESXi version and platform information to NetBox platform objects.
Host RoleDeviceRoleStaticnameAlways set to "ESXi Host" for all vCenter hosts.
Host InterfaceInterfacedevicename
spec.macprimary_mac_address
spec.ip.ipAddress + spec.ip.subnetMaskdescriptionMaps both virtual (vNIC) and physical (pNIC) interfaces with MAC addresses and IP configurations.
Virtual MachineVirtualMachinenamename
config.instanceUuidcustom_fields.vm_uuid
runtime.powerStatestatus
config.hardware.numCPUvcpus
config.hardware.memoryMBmemory
config.guestFullNameplatform.name
clustercluster
sitesiteMaps VM properties including name, UUID, power state, CPU/memory resources, guest OS, and cluster/site relationships.
VM RoleDeviceRoleStaticnameAlways set to "Virtual Machine" for all vCenter VMs.
VM PlatformPlatformconfig.guestFullNamenameMaps guest operating system information to NetBox platform objects.
VM InterfaceVMInterfacedeviceInfo.labelname
connectable.connectedenabled
macAddressprimary_mac_address
deviceInfo.summarydescription
virtual_switch_mtumtuMaps VM network adapters with connection status, MAC addresses, descriptions, and MTU information from associated virtual switches.
Virtual DiskVirtualDiskdeviceInfo.labelname
capacityInKBsize
backing.datastore.namecustom_fields.datastore_name
backing.fileNamecustom_fields.vmdk_file_pathMaps VM disk information including size (converted from KB to MB), datastore name, and VMDK file paths.
IP AddressIPAddressipAddress + subnetMaskaddress (CIDR)
device_idassigned_objectMaps both host and VM IP addresses with subnet masks converted to CIDR notation.
MAC AddressMACAddressmacAddressmac_addressMaps interface MAC addresses to NetBox MAC address objects for both hosts and VMs.
SiteSitenetbox_site:siteName (from tags) → name
StaticDefaultSiteCreates sites based on host tags or defaults to "DefaultSite" if no site information available.
Site GroupSiteGroupf"SiteGroup-{cluster.name}"nameCreates site groups for clusters spanning multiple sites using custom field relationships.
Cluster TypeClusterTypeStaticnameAlways set to "VMware vSphere" for all vCenter clusters.
ManufacturerManufacturersummary.hardware.vendornameMaps host hardware vendor information to NetBox manufacturer objects.

Field Mapping Details

Host Status Mapping

vCenter Power StateNetBox Status
poweredOnactive
poweredOffoffline
suspendedstaged
Any other valueoffline

VM Status Mapping

vCenter Power StateNetBox Status
poweredOnactive
poweredOffoffline
suspendedstaged
Any other valueoffline

Interface Type Mapping

vCenter Interface TypeNetBox Interface Type
vnic (Virtual NIC)other
pnic (Physical NIC)other
VM Network Adaptervirtual

Site Discovery Logic

The integration uses a sophisticated site discovery mechanism:

  1. Tag-based Discovery: Hosts with netbox_site:siteName tags create sites with the specified names
  2. Default Site Fallback: Hosts without site tags are assigned to "DefaultSite"
  3. Multi-site Clusters: Clusters spanning multiple sites create SiteGroups with custom field relationships

Cluster Scoping Logic

Host Site DistributionCluster Scope
Single sitescope_site
Multiple sitesscope_site_group (creates SiteGroup)
No site infoscope_site (DefaultSite)

IP Address Processing

The integration processes IP addresses with advanced logic:

  • CIDR Conversion: Automatically converts subnet masks to CIDR notation
  • Primary IP Assignment: First IPv4/IPv6 addresses become primary IPs for hosts and VMs
  • Interface Association: IP addresses are linked to specific interfaces via assigned_object relationships

MTU Discovery

VM interface MTU values are retrieved from:

  • Standard vSwitches: From host network system configuration
  • Distributed vSwitches: From DVS manager configuration
  • Fallback: Defaults to None if MTU cannot be determined

Data Flow

  1. Authentication: Establishes connection to vCenter using pyVmomi with retry mechanism
  2. Datacenter Discovery: Traverses vCenter hierarchy to identify datacenters and compute resources
  3. Host Discovery: Collects ESXi host information including hardware details, interfaces, and tags
  4. Cluster Discovery: Identifies clusters and standalone hosts within each datacenter
  5. VM Discovery: Gathers virtual machine details including hardware configuration and network adapters
  6. Site Resolution: Processes host tags to determine site assignments and create site hierarchies
  7. Entity Building: Creates NetBox entities with proper relationships and custom fields
  8. Data Ingestion: Sends entities to NetBox via Diode for processing

Custom Fields

The integration requires and utilizes several custom fields:

Custom FieldObject TypePurpose
vm_uuidVirtual MachineStores vCenter VM instance UUID
datastore_nameVirtual DiskStores associated vCenter datastore name
vmdk_file_pathVirtual DiskStores VMDK file path information
parent_site_groupsSiteLinks sites to parent site groups for multi-site clusters

Tags and Metadata

All objects created by the integration are tagged with:

  • vmware
  • vcenter
  • discovered

Additional tags from vCenter (excluding netbox_site: tags) are preserved and added to the tag list.

Notes

  • Site Creation: Sites are created automatically based on host tags or default to "DefaultSite"
  • Duplicate Handling: The integration handles duplicate entities by reusing existing NetBox objects
  • Fallback Values: Default values are provided for missing or invalid data
  • MAC Address Normalization: MAC addresses are converted to uppercase format
  • IP Address Validation: Only valid IP addresses with proper subnet masks are processed
  • Standalone Hosts: Hosts outside clusters are grouped into datacenter-specific standalone clusters
  • SSL Handling: Supports SSL certificate validation bypass for development/testing environments