netbox-pdm — Proxmox Datacenter Manager

netbox-pdm is a standalone NetBox plugin that inventories Proxmox Datacenter Manager (PDM) infrastructure. PDM is the centralized management plane that sits above individual Proxmox VE clusters and PBS servers. netbox-pdm reflects PDM endpoint metadata and the remotes they manage (PVE nodes and PBS servers) into NetBox, and links them to the ProxmoxEndpoint and PBSServer objects tracked by the sibling plugins.

Architecture

graph TB
    PDM["Proxmox Datacenter Manager\n(central mgmt plane)"]
    API["proxbox-api\n/pdm/sync/*"]
    NB["NetBox\nnetbox-pdm"]

    PDM -- "PDM REST API\n(:8443)" --> API
    API -- "JSON sync" --> NB

    NB --> EP["PDMEndpoint\n(one PDM server)"]
    NB --> REM["PDMRemote\n(PVE or PBS managed by PDM)"]
    EP -- "M2M" --> PROXMOX["netbox-proxbox\nProxmoxEndpoint"]
    EP -- "M2M" --> PBS["netbox-pbs\nPBSServer"]
    REM -- "FK (optional)" --> PROXMOX
    REM -- "FK (optional)" --> PBS

Data Models

PDMEndpoint

Mirrors one Proxmox Datacenter Manager server registered in NetBox.

Field	Type	Description
name	string	Human-readable label (unique)
host	string	Hostname or IP address
port	int	API port (default 8443)
token_id	string	PDM API token identifier
token_secret_encrypted	string	Bearer token secret, stored encrypted at rest
fingerprint	string	TLS fingerprint for certificate pinning
verify_ssl	bool	Whether to verify TLS certificates
allow_writes	bool	Reserved — enables write-back operations (default false)
timeout_seconds	int	Per-request timeout (default 30)
last_seen_at	datetime	Most recent successful API contact
site	FK → dcim.Site	Physical site
tenant	FK → tenancy.Tenant	Tenant scoping
proxmox_endpoints	M2M → ProxmoxEndpoint	Proxmox VE clusters managed through this PDM
pbs_servers	M2M → PBSServer	PBS servers managed through this PDM

PDMRemote

One row of PDM's /pdm/remotes response — a single PVE cluster or PBS server that PDM has discovered and is managing.

Field	Type	Description
pdm_endpoint	FK → PDMEndpoint	Parent PDM server
name	string	Remote name as reported by PDM
remote_type	choice	pve (Proxmox VE) or pbs (Proxmox Backup Server)
version	string	Proxmox version string reported by the remote
last_seen_at	datetime	Most recent successful contact
linked_proxmox_endpoint	FK → ProxmoxEndpoint (nullable)	Links to the matching netbox-proxbox endpoint
linked_pbs_server	FK → PBSServer (nullable)	Links to the matching netbox-pbs server

Uniqueness constraint: (pdm_endpoint, name).

PDMPluginSettings

Singleton settings row editable from PDM → Plugin Settings in the NetBox UI.

Field	Default	Description
proxbox_api_url	""	Fallback URL used when FastAPIEndpoint resolution is unavailable
proxbox_api_key	""	Optional bearer token for the standalone URL
branching_enabled	false	Create a netbox-branching branch per sync run
branch_name_prefix	"pdm-sync"	Prefix for auto-created branch names
branch_on_conflict	abort	abort (leave branch open) or overwrite (merge despite conflicts)
pdm_fetch_concurrency	8	Maximum concurrent requests when fetching PDM data
pdm_enabled	true	Master switch — disabling skips all PDM sync operations

Sync Flow

flowchart TD
    A([Operator triggers sync]) --> B{pdm_enabled?}
    B -- No --> Z([Skipped])
    B -- Yes --> C{Branching enabled?}
    C -- No --> D[PDMSyncJob on RQ default queue]
    C -- Yes --> E[Create netbox-branching branch\nprefix: pdm-sync-*]
    E --> D
    D --> F["POST /pdm/sync/endpoints"]
    D --> G["POST /pdm/sync/remotes"]
    F & G --> H[Link remotes → ProxmoxEndpoint / PBSServer]
    H --> I{Branching enabled?}
    I -- No --> J([Done])
    I -- Yes --> K{Conflicts?}
    K -- abort --> L([Branch left open for review])
    K -- overwrite --> M[Merge branch into main]
    M --> J

Cross-Plugin Relationships

netbox-pdm is the only companion plugin that references models from two sibling plugins:

erDiagram
    PDMEndpoint {
        string name
        string host
        int port
    }
    PDMRemote {
        string name
        string remote_type
        string version
    }
    ProxmoxEndpoint {
        string name
    }
    PBSServer {
        string name
    }

    PDMEndpoint ||--o{ PDMRemote : "remotes"
    PDMEndpoint }o--o{ ProxmoxEndpoint : "proxmox_endpoints (M2M)"
    PDMEndpoint }o--o{ PBSServer : "pbs_servers (M2M)"
    PDMRemote }o--o| ProxmoxEndpoint : "linked_proxmox_endpoint (nullable FK)"
    PDMRemote }o--o| PBSServer : "linked_pbs_server (nullable FK)"

Install order

Because PDMEndpoint references PBSServer, you must run python3 manage.py migrate netbox_pbs before python3 manage.py migrate netbox_pdm.

Navigation

The plugin registers a PDM top-level menu with an Inventory group:

• PDM Endpoints — list / detail / add
• PDM Remotes — list / detail
• Plugin Settings — singleton edit

REST API

The plugin exposes a read-write REST API under /api/plugins/pdm/:

Endpoint	Methods
/api/plugins/pdm/endpoints/	GET, POST
/api/plugins/pdm/remotes/	GET, POST
/api/plugins/pdm/settings/	GET, PUT, PATCH

Installation

Dependencies

netbox-proxbox and netbox-pbs must be installed and migrated before netbox-pdm.

pip

source /opt/netbox/venv/bin/activate
pip install netbox-pbs netbox-pdm

git (development build)

source /opt/netbox/venv/bin/activate
pip install git+https://github.com/emersonfelipesp/netbox-pdm.git

Enable in NetBox

Add to configuration.py in this order:

PLUGINS = [
    "netbox_proxbox",
    "netbox_pbs",   # must come before netbox_pdm
    "netbox_pdm",
]

Run migrations and restart:

cd /opt/netbox/netbox
python3 manage.py migrate netbox_pbs
python3 manage.py migrate netbox_pdm
python3 manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

Docker

Add to plugin_requirements.txt:

netbox-pbs
netbox-pdm

Add to configuration/plugins.py:

PLUGINS = [
    "netbox_proxbox",
    "netbox_pbs",
    "netbox_pdm",
]

Configuration

No PLUGINS_CONFIG entries are required. All runtime options are stored in the PDMPluginSettings singleton and editable from PDM → Plugin Settings.

NetBox Compatibility

netbox-pdm	NetBox
0.0.1+	4.5.8 – 4.6.x