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 Object | NetBox Object Type | Key Fields Mapped | Mapping Details |
---|---|---|---|
Datacenter | ClusterGroup | name → name | Maps vCenter datacenter names to NetBox cluster groups for organizational hierarchy. |
Cluster | Cluster | name → name | |
datacenter.name → group | |||
hosts[] → scope_site or scope_site_group | Maps vCenter clusters to NetBox clusters, scoped to sites or site groups based on host distribution. | ||
ESXi Host | Device | summary.config.name → name | |
summary.hardware.vendor → manufacturer.name | |||
summary.hardware.model → device_type.model | |||
hardware.systemInfo.serialNumber → serial | |||
config.product.fullName → platform.name | |||
runtime.powerState → status | |||
site_name (from tags) → site | Maps host hardware details, platform information, and operational status. Site assignment based on netbox_site: tags or defaults to "DefaultSite". | ||
Host Device Type | DeviceType | summary.hardware.model → model | |
summary.hardware.vendor → manufacturer | Creates device types based on host hardware model and vendor information. | ||
Host Platform | Platform | config.product.fullName → name | Maps ESXi version and platform information to NetBox platform objects. |
Host Role | DeviceRole | Static → name | Always set to "ESXi Host" for all vCenter hosts. |
Host Interface | Interface | device → name | |
spec.mac → primary_mac_address | |||
spec.ip.ipAddress + spec.ip.subnetMask → description | Maps both virtual (vNIC) and physical (pNIC) interfaces with MAC addresses and IP configurations. | ||
Virtual Machine | VirtualMachine | name → name | |
config.instanceUuid → custom_fields.vm_uuid | |||
runtime.powerState → status | |||
config.hardware.numCPU → vcpus | |||
config.hardware.memoryMB → memory | |||
config.guestFullName → platform.name | |||
cluster → cluster | |||
site → site | Maps VM properties including name, UUID, power state, CPU/memory resources, guest OS, and cluster/site relationships. | ||
VM Role | DeviceRole | Static → name | Always set to "Virtual Machine" for all vCenter VMs. |
VM Platform | Platform | config.guestFullName → name | Maps guest operating system information to NetBox platform objects. |
VM Interface | VMInterface | deviceInfo.label → name | |
connectable.connected → enabled | |||
macAddress → primary_mac_address | |||
deviceInfo.summary → description | |||
virtual_switch_mtu → mtu | Maps VM network adapters with connection status, MAC addresses, descriptions, and MTU information from associated virtual switches. | ||
Virtual Disk | VirtualDisk | deviceInfo.label → name | |
capacityInKB → size | |||
backing.datastore.name → custom_fields.datastore_name | |||
backing.fileName → custom_fields.vmdk_file_path | Maps VM disk information including size (converted from KB to MB), datastore name, and VMDK file paths. | ||
IP Address | IPAddress | ipAddress + subnetMask → address (CIDR) | |
device_id → assigned_object | Maps both host and VM IP addresses with subnet masks converted to CIDR notation. | ||
MAC Address | MACAddress | macAddress → mac_address | Maps interface MAC addresses to NetBox MAC address objects for both hosts and VMs. |
Site | Site | netbox_site:siteName (from tags) → name | |
Static → DefaultSite | Creates sites based on host tags or defaults to "DefaultSite" if no site information available. | ||
Site Group | SiteGroup | f"SiteGroup-{cluster.name}" → name | Creates site groups for clusters spanning multiple sites using custom field relationships. |
Cluster Type | ClusterType | Static → name | Always set to "VMware vSphere" for all vCenter clusters. |
Manufacturer | Manufacturer | summary.hardware.vendor → name | Maps host hardware vendor information to NetBox manufacturer objects. |
Field Mapping Details
Host Status Mapping
vCenter Power State | NetBox Status |
---|---|
poweredOn | active |
poweredOff | offline |
suspended | staged |
Any other value | offline |
VM Status Mapping
vCenter Power State | NetBox Status |
---|---|
poweredOn | active |
poweredOff | offline |
suspended | staged |
Any other value | offline |
Interface Type Mapping
vCenter Interface Type | NetBox Interface Type |
---|---|
vnic (Virtual NIC) | other |
pnic (Physical NIC) | other |
VM Network Adapter | virtual |
Site Discovery Logic
The integration uses a sophisticated site discovery mechanism:
- Tag-based Discovery: Hosts with
netbox_site:siteName
tags create sites with the specified names - Default Site Fallback: Hosts without site tags are assigned to "DefaultSite"
- Multi-site Clusters: Clusters spanning multiple sites create SiteGroups with custom field relationships
Cluster Scoping Logic
Host Site Distribution | Cluster Scope |
---|---|
Single site | scope_site |
Multiple sites | scope_site_group (creates SiteGroup) |
No site info | scope_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
- Authentication: Establishes connection to vCenter using pyVmomi with retry mechanism
- Datacenter Discovery: Traverses vCenter hierarchy to identify datacenters and compute resources
- Host Discovery: Collects ESXi host information including hardware details, interfaces, and tags
- Cluster Discovery: Identifies clusters and standalone hosts within each datacenter
- VM Discovery: Gathers virtual machine details including hardware configuration and network adapters
- Site Resolution: Processes host tags to determine site assignments and create site hierarchies
- Entity Building: Creates NetBox entities with proper relationships and custom fields
- Data Ingestion: Sends entities to NetBox via Diode for processing
Custom Fields
The integration requires and utilizes several custom fields:
Custom Field | Object Type | Purpose |
---|---|---|
vm_uuid | Virtual Machine | Stores vCenter VM instance UUID |
datastore_name | Virtual Disk | Stores associated vCenter datastore name |
vmdk_file_path | Virtual Disk | Stores VMDK file path information |
parent_site_groups | Site | Links 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