[TUTORIAL] Terraform module for Proxmox SDN: zones, VNets, DHCP, and SNAT

[hybridops]

Built a Terraform module for managing Proxmox SDN declaratively: zone, VNets, subnets, host gateway IPs on the `vnet*` bridges, SNAT/masquerade rules, and dnsmasq DHCP from a single `vnets` map.

The two modes that ended up being most useful in practice:

• Host-routed: Proxmox owns L3, NAT, and DHCP.
• Edge-routed: Proxmox SDN handles segmentation while an external edge such as VyOS owns routing and DHCP.

It also supports a few details that mattered in real use:

• DHCP defaults from subnet CIDRs with per-subnet overrides
• host-side reconcile without mutating the topology model
• exported prefix data shaped for NetBox/IPAM workflows

GitHub: https://github.com/hybridops-tech/terraform-proxmox-sdn

Terraform Registry: `hybridops-tech/sdn/proxmox`

 

[Sviat]

Hi,

it could good fit for lab environments where automation and rebuildability matter more than uptime stability, but it’s risky for production use unless you have strong safeguards and out-of-band access.
The main risk could come during updates or changes, where applying Terraform can temporarily disrupt networking by reconfiguring bridges or restarting DHCP, potentially breaking connectivity if you’re connected remotely without console access.
Did you test it on environment with real load?
BTW you do not need to duplicate you post twice, it looks like a spam

 

[hybridops]

Fair point on the blast radius. Any tool touching hypervisor networking needs respect.

The module is not just doing a blind apply though. A lot of the work went into making re-apply/reconcile safe:

• SDN reload waits for the expected `vnet*` interfaces
• gateway/NAT/DHCP setup runs after SDN is actually present
• gateway config uses `ip addr replace`
• NAT rules are tagged and checked before adding
• DHCP is per-VNet dnsmasq units, not one shared global restart
• `host_reconcile_nonce` can force host-side gateway/NAT/DHCP reconcile without changing the topology

So I would still want console/OOB access for serious changes, but the intent is not “apply once and hope”. It is meant to be safely re-applied when the module owns that SDN layer.

For production-style setups I’d usually prefer edge-routed anyway: Proxmox SDN handles segmentation, VyOS/edge handles routing and DHCP. Host-routed is more for labs, bootstrap, or smaller sites where Proxmox intentionally owns L3.

And yes, the duplicate post was my mistake. Not intentional spam.