https://github.com/patricklind/proxmox2netbox
Netbox Plugin for integration between Proxmox and Netbox
https://github.com/patricklind/proxmox2netbox
netbox-plugin proxmox
Last synced: 10 days ago
JSON representation
Netbox Plugin for integration between Proxmox and Netbox
- Host: GitHub
- URL: https://github.com/patricklind/proxmox2netbox
- Owner: patricklind
- License: apache-2.0
- Created: 2026-02-24T18:11:15.000Z (16 days ago)
- Default Branch: main
- Last Pushed: 2026-03-01T14:49:15.000Z (11 days ago)
- Last Synced: 2026-03-01T19:30:43.792Z (11 days ago)
- Topics: netbox-plugin, proxmox
- Language: Python
- Homepage:
- Size: 5.48 MB
- Stars: 2
- Watchers: 0
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# 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.1.4`
## 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`
- Endpoint metadata refresh (`mode`, `version`, `repoid`, cluster name)
- Sync process tracking in `SyncProcess`
## 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:
```bash
pip install proxmox2netbox
```
If you run `netbox-docker`, also pin the package in your Docker requirements file so it survives rebuilds/redeploys:
```text
# local_requirements.txt
proxmox2netbox==1.1.4
```
### 2. Enable plugin
In NetBox `configuration.py`:
```python
PLUGINS = ["proxmox2netbox"]
```
### 3. Run migrations/static
```bash
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:
```python
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
```bash
ruff check proxmox2netbox --select F401,F403,F811,F821,F841,E712
python -m compileall -q proxmox2netbox
```
### Django checks (inside NetBox runtime)
```bash
python manage.py check
python manage.py makemigrations --check --dry-run
```
### Tests
Current repository state contains no active pytest test modules.
```bash
pytest
# expected: no tests ran
```
## Publish to PyPI
### Prerequisites
- You must have access to the [`proxmox2netbox`](https://pypi.org/project/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
```bash
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:
```bash
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:
```bash
pip install proxmox2netbox
```
## Repository Layout (Relevant Runtime Files)
```text
proxmox2netbox/
__init__.py
jobs.py
models/
services/
proxmox_sync.py
proxmox_sync.py # compatibility shim
views/
sync.py
keepalive_status.py
cards.py
urls.py
forms/
filtersets.py
tables/
```
## 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/`