Use

NetBox provisioning

Create iac guests from NetBox and track their deployment status there.

iac can use NetBox as the source for guest creation. You describe a virtual machine in NetBox; the optional iac-provisioner then runs the usual iac ct.sh or vm.sh on the selected Proxmox node. This uses the same installation flow as a manual deployment.

Set it up

Install NetBox with the provisioner module enabled. It adds the iac-managed tag, the required custom fields and app/type/module choices. Install iac-provisioner as an iac guest and configure its NetBox API access and SSH access to the Proxmox nodes. Keep the provisioner on a trusted network: its SSH key grants root access to those nodes.

Tag only the virtual machines that iac should manage with iac-managed. Set their status to planned, select the app and guest type (LXC or VM), and provide the target node. Configure resources and network details on the VM and its interfaces. The iac Config Context supplies optional defaults such as storage, bridge, DNS and SSH keys. An empty VMID is allocated by Proxmox and written back to NetBox.

What happens

The provisioner checks for planned guests every five minutes; a signed NetBox webhook can also start a check sooner. It marks a guest staged before starting the deployment, to avoid duplicate runs. On success, NetBox is updated to active with the VMID and MAC address. On failure, the status becomes failed and the error and host log location are added to the NetBox journal. A guest left staged after a provisioner restart is marked failed and is not retried automatically; inspect the guest and reset its status to planned when it is safe to try again.

The current integration creates guests only. It does not yet apply later resource changes or remove guests when their NetBox status changes.

See Install for manual and command-line deployment options.