proxmox2netbox 1.2.9

NetBox plugin for synchronizing Proxmox inventory data

Proxmox2NetBox

NetBox plugin for synchronizing Proxmox inventory data into NetBox (NetBox v4).

Compatibility

• NetBox: >=4.2.0, <5.0.0
• Python: >=3.8
• Plugin package version in this repository: 1.2.9

What Works (Current Runtime)

Out-of-the-box sync requires only a configured Proxmox Endpoint in NetBox.

Implemented sync flows:

• Proxmox nodes → NetBox dcim.Device
• Proxmox QEMU/LXC VMs → NetBox virtualization.VirtualMachine
• VM interfaces from Proxmox config → NetBox virtualization.VMInterface, with per-interface IP assignment
• QEMU guest-agent IPs as fallback when static config lacks IPs (MAC-based interface matching)
• Endpoint-level Site and VRF mapping — devices and IPs are placed in the correct NetBox Site/VRF
• Endpoint-level Node Device Type — select a real NetBox DeviceType (e.g. Dell PowerEdge R740) for synced nodes; falls back to generic Proxmox Node type
• Per-node Device Type Mapping — override device type per individual node name via Node Type Mappings UI (Plugins → Proxmox2NetBox → Configuration → Node Type Mappings)
• Endpoint metadata refresh (mode, version, repoid, cluster name)
• Sync process tracking in SyncProcess
• Stale IP cleanup — IPs removed from Proxmox config are removed from NetBox interfaces

Runtime Architecture (Source of Truth)

Core sync logic is consolidated in:

• proxmox2netbox/services/proxmox_sync.py

Backward-compatible import shim (kept intentionally):

• proxmox2netbox/proxmox_sync.py

Primary runtime entrypoints:

• UI endpoints: proxmox2netbox/views/sync.py
• Connection/status badge: proxmox2netbox/views/keepalive_status.py
• Proxmox card data: proxmox2netbox/views/cards.py
• Job wrapper: proxmox2netbox/jobs.py (Proxmox2NetBoxSyncJob)

Installation (NetBox v4)

1. Install plugin package

Inside NetBox environment:

pip install proxmox2netbox

If you run netbox-docker, also pin the package in your Docker requirements file so it survives rebuilds/redeploys:

# local_requirements.txt
proxmox2netbox==1.2.9

2. Enable plugin

In NetBox configuration.py:

PLUGINS = ["proxmox2netbox"]

3. Run migrations/static

python manage.py migrate
python manage.py collectstatic --no-input

Configure and Run Sync

Configure Proxmox Endpoint

In NetBox UI:

• Plugins -> Proxmox2NetBox -> Endpoints -> Proxmox Endpoints
• Create at least one endpoint with:
  • username
  • either password or (token_name + token_value)
  • host via domain and/or ip_address

Run sync from UI

• Plugins -> Proxmox2NetBox -> Full Update
• Available actions:
  • Sync Nodes
  • Sync Virtual Machines
  • Full Update Sync

Run sync as NetBox Job (wrapper)

jobs.py provides a queue-compatible wrapper around the existing service layer.

Example from NetBox shell:

from proxmox2netbox.jobs import Proxmox2NetBoxSyncJob
from proxmox2netbox.choices import SyncTypeChoices

# Full sync
Proxmox2NetBoxSyncJob.enqueue(sync_type=SyncTypeChoices.ALL)

# Devices only
Proxmox2NetBoxSyncJob.enqueue(sync_type=SyncTypeChoices.DEVICES)

# Virtual machines only
Proxmox2NetBoxSyncJob.enqueue(sync_type=SyncTypeChoices.VIRTUAL_MACHINES)

Behavior note:

• Job class is an orchestrator only.
• Sync mapping, payloads, and upsert logic remain in services/proxmox_sync.py.

Development & Validation

Static checks

ruff check proxmox2netbox --select F401,F403,F811,F821,F841,E712
python -m compileall -q proxmox2netbox

Django checks (inside NetBox runtime)

python manage.py check
python manage.py makemigrations --check --dry-run

Tests

Current repository state contains no active pytest test modules.

pytest
# expected: no tests ran

Publish to PyPI

Prerequisites

• You must have access to the proxmox2netbox project on PyPI.
• If the name is unavailable for your account, change project.name in pyproject.toml to a unique name before publishing.
• Configure one of these publish methods:
• Add PYPI_API_TOKEN as a repository secret in GitHub, or
• Configure a matching Trusted Publisher in PyPI for this GitHub repository/workflow:
• Owner: patricklind
• Repository: Proxmox2Netbox
• Workflow file: .github/workflows/publish-python-package.yml
• Environment name: pypi

Local preflight

python -m build
twine check dist/*

Publish via GitHub Actions

• Bump version in pyproject.toml and plugin config version in source.
• Create and push a tag:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

• release.yml creates the GitHub Release from the tag and dispatches package publish.
• publish-python-package.yml publishes to PyPI (release event and manual/dispatch supported).
• After publish:

pip install proxmox2netbox

Repository Layout (Relevant Runtime Files)

proxmox2netbox/
  __init__.py
  jobs.py
  choices.py
  filtersets.py
  navigation.py
  models/
    __init__.py              # ProxmoxEndpoint, ProxmoxNodeTypeMapping, SyncProcess
  services/
    proxmox_sync.py          # Core sync logic (nodes, VMs, interfaces, IPs)
  proxmox_sync.py            # Backward-compat import shim
  views/
    __init__.py
    sync.py
    keepalive_status.py
    cards.py
    node_type_mapping.py     # CRUD views for ProxmoxNodeTypeMapping
  forms/
    __init__.py
    proxmox.py               # Endpoint + NodeTypeMapping forms
  tables/
    __init__.py
  api/
    serializers.py           # Exposes netbox_site, netbox_vrf, netbox_device_type
  migrations/
    0001_initial.py … 0016_proxmoxnodetypemapping_fix.py
  templates/
    proxmox2netbox/
      proxmoxendpoint.html
      proxmoxnodetypemapping.html
  urls.py

Scope

This repository ships a NetBox plugin runtime only.
Legacy FastAPI/backend-service components are removed from runtime, docs, and packaging scope.

Wiki

• GitHub Wiki URL: https://github.com/patricklind/Proxmox2Netbox/wiki
• Wiki source files in this repository: wiki/