Skip to content

Proxmox SDN as Reusable Network Foundation

Overview

Proxmox SDN as Reusable Network Foundation replaces manual bridge edits, subnet setup, and DHCP drift with one repeatable network baseline. The same control path can support host-routed bootstrap environments, edge-routed production designs, and IPAM export for downstream consumers.

It is the network layer that later NetBox, Kubernetes, WAN, and DR services depend on.

Case study

  • Context: Proxmox networking was configured through manual bridge edits applied directly to nodes. There was no repeatable path, no IPAM export, and no consistent topology model across environments.
  • Challenge: adding or changing network segments required direct node access and often left the Proxmox GUI in an inconsistent state that could not be corrected without rebuilding objects.
  • Approach: hybridops-tech/sdn/proxmox was extracted as a standalone, versioned Terraform module with explicit zone, VNet, and subnet contracts. HybridOps consumes the released module through core/onprem/network-sdn, keeping the topology definition separate from the runtime that resolves and executes it.
  • Outcome: zone shybzone is delivered repeatably from a released module version (v0.1.6). Host-routed and edge-routed designs share the same topology contract, Proxmox exposes the applied SDN state, and IPAM-ready data is available for downstream consumers.

Covers SDN apply, zone and VNet delivery, host-routed versus edge-routed posture, and the live Proxmox zone state after the apply run.

Outcome

The result is a reusable on-prem network substrate with a versioned topology contract and visible applied state.

  • Segmented VLAN-backed networking is delivered through one controlled path.
  • Host-routed and edge-routed operating modes share the same topology model.
  • Proxmox remains authoritative for the applied SDN objects and live network state.
  • IPAM-ready topology data can be exported for downstream consumers.

Operating model

  • The released Terraform module defines the SDN zone, VNets, subnets, and optional host-service contract.
  • HybridOps consumes that released module through core/onprem/network-sdn, resolving version, inputs, and execution policy.
  • Proxmox remains authoritative for the resulting applied SDN objects and current network state.
  • Host routing, DHCP, and NAT are optional behaviours under the same topology contract.
  • The baseline supports bootstrap estates and later edge-routed production designs without changing the operator-facing network model.

Architecture

Proxmox SDN architecture showing the released public topology module, the HybridOps runtime consumer, Proxmox applied SDN state, the resulting network substrate, and optional host services, topology export, and downstream platform consumers.

The published Terraform module is the versioned topology contract; HybridOps resolves and executes it through core/onprem/network-sdn; Proxmox remains authoritative for the applied SDN objects and live network state. Optional host services, topology export, and downstream platform consumers derive from that substrate without collapsing declared topology into live-state authority.

Control sequence

  1. The released Terraform module defines the zone, VNets, subnet behaviour, and optional host services.
  2. HybridOps resolves and executes that module through the on-prem SDN runtime path.
  3. Proxmox applies and exposes the resulting SDN objects and live state.
  4. Host services, topology export, and downstream platform paths consume the applied network substrate.

Platform state

Proxmox node inventory on hybridhub, showing the downstream VM estate consuming the SDN baseline
Downstream VM estate consuming the shared SDN foundation.
Proxmox VNets view with shybzone and the management, data, workload, and staging VNets visible with their VLAN tags
Management, data, workload, and staging VNets with assigned VLAN tags.

IP addresses, hostnames, and instance identifiers visible in screenshots and recordings reflect the ephemeral infrastructure provisioned during the recorded exercise.

Implementation

  • Released topology contract: hybridops-tech/sdn/proxmox is the versioned module surface.
  • Runtime consumer: core/onprem/network-sdn resolves and executes the released baseline in HybridOps.
  • Applied authority: Proxmox owns the active SDN objects and current network state.
  • Operator posture: host-routed and edge-routed designs stay under one topology contract.
  • Downstream use: topology export, VM delivery, Kubernetes, WAN extension, and DR consume the shared network substrate.

Key components

Where it fits

  • Proxmox estates replacing manual network administration with a repeatable baseline
  • bootstrap environments that begin host-routed and later move to edge-routed designs
  • on-prem platforms preparing for NetBox, RKE2, WAN, or DR delivery

References

Further reading
Implementation references
  • core/onprem/network-sdn
  • hybridops-tech/sdn/proxmox

What was verified

Verified against HybridOps v1.0.1 and hybridops-tech/sdn/proxmox v0.1.6 with the shared on-prem SDN zone active.