Proxmox VE Integration

Overview

The NetBox Proxmox VE integration provides comprehensive synchronization of Proxmox Virtual Environment (Proxmox VE) infrastructure into NetBox, enabling organizations to maintain a unified view of their hypervisor nodes, virtual machines, LXC containers, networking, and storage within their NetBox environment.

What Gets Synchronized

• Cluster (Proxmox VE cluster, with cluster type)
• Devices (Proxmox VE nodes — as NetBox Devices with role "Hypervisor")
• Device Interfaces (node network interfaces with type, speed, and MTU)
• Virtual Machines (QEMU KVM VMs and LXC containers)
• VM Interfaces (virtual network interfaces with MAC addresses and VLAN tags)
• IP Addresses (from QEMU guest agent or LXC network config, with primary IP assignment)
• Prefixes (network subnets derived from node interface addresses)
• VLANs (from node VLAN interfaces and VM interface VLAN tags)
• Virtual Disks (disk devices for VMs and containers with storage pool metadata)
• Platforms (OS-specific per node from PVE version string, per VM from ostype or guest agent)

Technical Info

For full details of Proxmox VE to NetBox object and attribute mappings, please refer to the Technical Info section.

Key Features

• Automated Discovery: Automatically discovers and synchronizes Proxmox VE infrastructure data into NetBox
• Scheduled Synchronization: Configurable schedule (every 30 minutes, hourly, daily, etc.) keeps NetBox data current with your Proxmox VE cluster
• API Token Authentication: Secure token-based authentication to the Proxmox VE API — no password required
• Guest Agent IP Discovery: Retrieves accurate IP addresses from the QEMU guest agent for virtual machines
• Node Scope Filtering: Optionally limit synchronization to specific Proxmox VE nodes
• Per-Node Site Mapping: Assign different NetBox sites to individual Proxmox nodes using NODE_SITE_MAP
• Cluster Name Detection: Automatically detects the Proxmox cluster name from the API, with optional override
• Bootstrap Mode: Creates required custom fields and schema objects in NetBox before the first data sync
• NetBox Assurance Integration: Leverages NetBox Assurance for safe data ingestion and deviation management
• Automatic Retry: Retries on transient API errors (429, 502, 503, 504) with backoff

Integration Architecture

The Proxmox VE integration is built using the NetBox Labs controller integrations framework, which provides:

• Standardized Integration Pattern: Consistent approach across all controller integrations
• NetBox Assurance Integration: Built-in support for safe data ingestion and deviation management with NetBox Assurance
• Agent Based: Runs as part of the NetBox Discovery agent ecosystem using the Orb Agent Pro image

Compatibility

Supported NetBox Versions

• NetBox Cloud and NetBox Enterprise v4.2.3 and later with NetBox Assurance

Supported Proxmox VE Versions

• Proxmox VE 7.x and later (API token authentication required)