Skip to content

High Availability (HA)

netbox-proxbox surfaces Proxmox cluster High-Availability state directly inside NetBox so operators can answer "is this VM HA-managed and what's its current state?" without leaving the inventory UI.

There are two entry points:

  • A HA tab on every virtualization.VirtualMachine detail page, scoped to that VM.
  • A HA Status page (/plugins/proxbox/ha/) showing cluster-wide HA state — nodes, groups, and every HA-managed resource.

Both views are read-only and fetched live from the proxbox-api backend on every request. There is no NetBox-side caching, no persisted HA model, and no migration. Stop the proxbox-api service and the pages render an inline error banner instead of a 500.

Backend floor

HA views require proxbox-api >= 0.0.12. Older backends return 404 on the new routes and both views show an inline upgrade banner instead of failing. The full upstream contract lives in proxbox-api Cluster HA API.

Visibility

The VM HA tab only registers when the VM has a resolvable ProxboxVirtualMachineSyncState.proxmox_vm_id. VMs that were never synced through Proxbox, and therefore have no populated sidecar, will not show the tab. The cluster-wide HA Status page is always available under Plugins → Proxbox → HA Status regardless of any single VM's sync state.

VM HA Tab

The tab appears next to Proxmox Config on each VirtualMachine detail page (slot weight 1400).

When the VM has a resolvable Proxmox VM ID it issues:

GET /proxmox/cluster/ha/resources/by-vm/{vmid}

The backend tries SID vm:{vmid} first and falls back to ct:{vmid}, returning null (not 404) when neither is HA-managed. The tab renders:

  • HA managed yes/no, group, current state, CRM state, request state, node.
  • Counters — max-restart, max-relocate, failback.
  • Empty state — "This VM is not HA-managed in Proxmox." with a link to the cluster page.

If the proxbox-api backend is too old to expose the HA endpoints (i.e. < 0.0.12), the tab surfaces a clear "upgrade proxbox-api to v0.0.12 or later" message.

Cluster-wide HA Status Page

The HA Status menu entry under Proxbox routes to /plugins/proxbox/ha/. The view issues a single composed call:

GET /proxmox/cluster/ha/summary

The backend summary endpoint fans out four parallel HA reads via asyncio.gather and returns one envelope, so the plugin makes exactly one HTTP request per page render.

The page renders three sections:

  • Cluster Status — node-level CRM state and quorum, derived from rows in /cluster/ha/status/current where type == "node".
  • HA Groups — table of HA group definitions (name, member nodes, restricted, nofailback).
  • HA Resources — every HA-managed VM/CT (sid, group, current state, CRM state, max-restart, max-relocate). When a NetBox VirtualMachine has a typed sync-state row with the matching proxmox_vm_id, the SID column links to it.

When the cluster has no HA configured, each section renders an empty-state row instead of a missing table.

HA Arm / Disarm

Two POST endpoints arm or disarm the Proxmox HA stack (PVE 9.2+ cluster/ha/status/arm-ha / disarm-ha) from NetBox:

POST /plugins/proxbox/ha/arm/
POST /plugins/proxbox/ha/disarm/

These routes map to HaArmView and HaDisarmView in netbox_proxbox/views/ha_actions.py. They accept CSRF-protected session requests only and return JSON with one result per endpoint:

  • The caller needs the run_proxmox_action action on Proxmox endpoints. Grant it as an additional action on a NetBox object permission whose object type is Proxbox › Proxmox Endpoint; constraints limit which endpoints the user may arm or disarm.
  • Only enabled endpoints the caller holds that action on are in scope. An optional endpoint_id form field targets one of them (404 outside the caller's scope).
  • Endpoints with Allow Proxmox-side writes disabled are reported as endpoint_writes_disabled and never sent to the backend.
  • A result is ok: true only when proxbox-api returns a non-empty result list whose every row has status: ok. proxbox-api answers HTTP 200 even when a cluster rejects the command, so a per-cluster error is reported as failure.

Backend requirement

HA arm/disarm requires proxbox-api >= 0.0.14. Earlier backends do not expose the corresponding action routes.

Backend Paths

Plugin view Backend endpoint Purpose
VM HA tab GET /proxmox/cluster/ha/resources/by-vm/{vmid} Single resource for one VM/CT (null if unmanaged)
HA Status page GET /proxmox/cluster/ha/summary Composed {nodes, groups, resources, status} envelope
HA arm POST /plugins/proxbox/ha/arm/ Arm a Proxmox resource for HA management
HA disarm POST /plugins/proxbox/ha/disarm/ Remove a Proxmox resource from HA management

The plugin's REST shim that exposes both backend calls as JSON for non-HTML consumers is documented in Cluster HA API.

Permissions

  • The VM HA tab uses NetBox's standard virtualization.view_virtualmachine permission and restrict() so users only see HA state for VMs they may view.
  • HA arm/disarm requires the run_proxmox_action action on Proxmox endpoints (see above). Model-level change_proxmoxendpoint alone no longer grants it.
  • The cluster page reuses the plugin's dashboard mixin chain (ConditionalLoginRequiredMixin + RequireProxboxDashboardAccessMixin), so it follows the same access rules as the rest of the Proxbox UI.
  • The HA status page, the VM HA tab, and the HA REST API only ask proxbox-api about enabled Proxmox endpoints the caller may view (ProxmoxEndpoint.objects.restrict(user, "view")). An anonymous caller with LOGIN_REQUIRED = False sees HA data only when the Proxmox endpoint view permission is exempt.