netbox-proxbox Documentation

The edgeuno/netbox-proxbox plugin is a NetBox extension designed to import Proxmox VE inventory state into NetBox. It mirrors Proxmox clusters, nodes, virtual machines (VMs), and LXC containers into NetBox's dcim and virtualization applications.

Key Capabilities

• Proxmox to NetBox Importer: Performs read-only synchronization of Proxmox resources.
• Multi-cluster Support: The v2 sync engine allows a single configuration_options.json file to define multiple Proxmox clusters for a single sync run.
• Dual-mode Runtime:
  • Synchronous (v1): Triggered via the NetBox UI ("Full Update" button).
  • Asynchronous (v2): Triggered via a scheduled container using the proxboxscrapper command.

Important Limitations

• Read-Only: All Proxmox API interactions are GET requests; the plugin does not push state from NetBox to Proxmox.
• Fork Divergence: This is an EdgeUno fork and contains specific business logic (e.g., regex-based tenant assignment, role pinning to "VPS" and "LXC") that differs from the upstream netbox-proxbox project.

What it is

netbox-proxmox-automation is an event-driven integration that uses NetBox as the desired state source of truth for Proxmox VE workloads (VMs and LXC containers).

When a NetBox object is created, updated, or deleted, NetBox triggers a webhook via an event rule. This webhook is then translated into a Proxmox API operation (e.g., cloning a template, resizing a disk, starting/stopping a workload, or migrating between nodes).

Execution Paths

The project provides two interchangeable ways to handle webhooks:

1. AWX / Tower / AAP: Uses a set of Ansible playbooks executed by job templates triggered by webhooks.
2. Flask application: A small Flask + Flask-RESTX HTTP service that receives webhooks and calls the Proxmox API directly in-process.

Key Distinctions

• Not a NetBox plugin: It does not install Django apps, migrations, or models; it layers custom fields and event rules onto an existing NetBox instance.
• Not a continuous sync tool: Unlike ProxBox, it does not continuously sync Proxmox state back to NetBox. The only reverse flow (Proxmox $\rightarrow$ NetBox) occurs during one-shot discovery scripts.
• No reconciliation loop: The system is purely reactive. The webhook payload is the only trigger; there is no background scheduler or reconciliation loop to fix drift.

The Proxbox plugin organizes Proxmox-related data into several logical views within the NetBox interface:

Core Management

• Plugin Home: Displays endpoint status cards, quick-sync actions, and primary navigation.
• Dashboard: Provides operational summaries of clusters and nodes sourced from the proxbox-api backend.

Endpoint Configuration

• Proxmox Endpoints: Configuration for the Proxmox API endpoints the plugin connects to.
• FastAPI (Proxbox) Endpoints: Configuration for the companion proxbox-api backend.
• NetBox Endpoints: The self-referential NetBox endpoint used by proxbox-api for write-back operations.

Infrastructure & Virtualization

• Clusters: Discovered Proxmox clusters synchronized into NetBox.
• Nodes: Proxmox nodes (devices) associated with specific clusters.
• Storage: Proxmox storage pools tracked per cluster.
• Virtual Machines: Proxmox VMs synchronized into NetBox Virtualization.
• LXC Containers: Linux containers managed by Proxmox and tracked in NetBox.

Backup & Recovery

• Backups: VM backup jobs discovered from Proxmox storage.
• Snapshots: VM and container snapshots tracked per virtual machine.

This document provides a side-by-side comparison between the upstream netbox-proxbox (this repository) and the EdgeUno fork. While both aim to import Proxmox state into NetBox, they use fundamentally different architectures.

Upstream (netbox-proxbox + proxbox-api)

• Architecture: A two-service mirror model.
• Components: A NetBox plugin (UI, models, settings, RQ jobs) and a separate FastAPI backend (proxbox-api) that handles Proxmox/NetBox connection logic and the sync engine.
• Communication: Services communicate over HTTP/SSE/WebSocket using a pinned wire contract.
• Security: Encrypted credentials live in the backend's Fernet store, not in NetBox.
• Sync Mechanism: Triggered via RQ ProxboxSyncJob on NetBox's default queue; progress is streamed back to the plugin via SSE.

EdgeUno Fork

• Architecture: A single-process scrapper model.
• Components: A single NetBox plugin containing two embedded sync engines (proxbox_api/ synchronous and proxbox_api_v2/ asynchronous).
• Communication: The plugin talks directly to Proxmox and NetBox.
• Security: Configuration and plaintext credentials are stored in an external configuration_options.json file.
• Sync Mechanism: Triggered via a Django view, a management command (python manage.py proxboxscrapper), or a standalone container scheduler.

The netbox-sdk supports two types of NetBox authentication tokens:

1. Token v1: Uses the classic Authorization: Token <value> header.
2. Token v2: Uses the newer nbt_<key>.<secret> format. The SDK automatically handles the splitting and encoding of the key and secret.

When building a Config object (e.g., via netbox_config_from_endpoint), you specify the token_version as either "v1" or "v2". For v2, you must provide the token_key (the <key> portion) and the token_secret (the <secret> portion).

# Example of how the SDK config is constructed internally
def netbox_config_from_endpoint(endpoint: NetBoxEndpoint) -> Config:
    tv = (endpoint.token_version or "v1").lower()   # "v1" or "v2"
    return Config(
        base_url=endpoint.url,
        token_version=tv,
        token_key=key,          # v2 only: key portion of nbt_key.secret
        token_secret=decrypted_token,
        timeout=_resolve_netbox_timeout(),  # PROXBOX_NETBOX_TIMEOUT env var
        ssl_verify=endpoint.verify_ssl,
    )