NetBox-VM-Import/README.md

NetBox VMware Importer

Synchronise virtual machines from VMware vSphere / vCenter into NetBox.

Plugin name	netbox_vmware_importer
Package	netbox-vmware-importer
NetBox	4.6.5 – 4.7.1
Python	>=3.12
Repository	https://git.mrblake.cc/MrBlake/NetBox-VM-Import

Features

• Manage vCenter/ESXi endpoints directly in the NetBox web UI
• Tenant, site and NetBox cluster per endpoint
• Manual synchronisation via button
• Optional automatic synchronisation on a minute interval
• Imports VM name, status, vCPU, RAM, disk, platform, interfaces, MAC addresses and IPs
• MAC addresses are created as NetBox MAC address objects on the VM interface and set as primary MAC
• Virtual disks are documented as NetBox virtual disks with size and backing info
• Primary IPv4/IPv6 is set from the first guest IP found
• Multi-tenant-safe VM matching via name + cluster

The plugin intentionally does not delete orphaned VMs, interfaces or IP addresses. This keeps rollouts conservative and avoids data loss when VMware guest data is incomplete.

Compatibility

• NetBox 4.6.5 – 4.7.1
• Python >=3.12
• Dependencies installed automatically: pyvmomi, cryptography

Installation

All paths assume a standard installation under /opt/netbox.

1. Install the package

/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
  "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main"

For reproducible production installs, replace main with a release tag or a full commit ID.

2. Add the plugin to local_requirements.txt

This makes upgrade.sh reinstall the plugin automatically on every NetBox upgrade:

grep -qxF "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main" /opt/netbox/local_requirements.txt \
  || echo "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main" | sudo tee -a /opt/netbox/local_requirements.txt

If the repository is private, the NetBox server needs a read-only deploy token or an SSH key. Do not store credentials in local_requirements.txt.

3. Enable the plugin

In /opt/netbox/netbox/netbox/configuration.py:

PLUGINS = [
    "netbox_vmware_importer",
]

If other plugins are already configured, add netbox_vmware_importer to the existing list.

4. Apply migrations, collect static files, restart

cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate netbox_vmware_importer
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

Update

/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
  "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main"

cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate netbox_vmware_importer
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

--force-reinstall makes pip pick up branch changes even if the package version has not been bumped.

When NetBox itself is upgraded, upgrade.sh reinstalls the plugin from local_requirements.txt and runs migrations and collectstatic:

sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq

Upgrade note for 0.3.1

Version 0.3.1 fixes unstable Django migration dependencies from earlier releases. If migrate fails with InconsistentMigrationHistory for netbox_vmware_importer.0001_initial, first update the plugin to 0.3.1, then run manage.py migrate --plan and manage.py migrate normally. Manual changes to django_migrations or --fake should not be necessary.

Uninstall

1. Remove "netbox_vmware_importer" from PLUGINS.
2. Remove the line from /opt/netbox/local_requirements.txt.
3. Uninstall the package and restart NetBox:

/opt/netbox/venv/bin/pip uninstall netbox-vmware-importer
sudo systemctl restart netbox netbox-rq

Usage

1. In NetBox, create an endpoint under VMware Import > Endpoints.
2. Enter the vCenter/ESXi host, port, username and password.
3. Select tenant, site and cluster for the customer.
4. Optionally set regex filters and a sync interval.
5. On the detail page, click Start sync now.

If Sync interval minutes is set, a system job checks every five minutes which endpoints are due and enqueues the actual sync jobs.

Legacy Proxmox endpoints

Proxmox support has been removed. Old Proxmox endpoints from earlier versions remain visible in the list and detail view so they can be deleted; they can no longer be edited, created or synchronised.

Security

The endpoint password is stored encrypted in the plugin table. The key is derived from SECRET_KEY; if SECRET_KEY is rotated, the endpoint secrets must be set again. For very strict environments, an external secret store such as Vault is the next planned extension.

Data quality

IP addresses come from VMware Guest Tools. Without running or current Guest Tools, interfaces and IPs may be missing or outdated.