v0.1.7

Architecture

Last updated


This page shows, in one diagram, how QemuRun-pve's layers relate to the Proxmox cluster, and where the service sits among Go Proxmox tools.

System Overview


graph TB
    Client -->|HTTP / SSE| Gin[Gin Router + CORS]
    Gin --> Handler[Handler Layer<br/>ALLOW_IPS / state checks]
    Handler --> Util[Util<br/>VM / node lookup]
    Handler --> Service[Service Layer]
    Util -->|pvesh| PVE[(Proxmox Cluster API)]
    Util --> Disabled[.go_qemu_disabled]
    Service -->|qm / pvesh / pvesm| Main[Main Node]
    Service -->|SSH root@NODE_x + qm| Remote[Remote Node]
    Service -->|HTTP| Mirror[Official Cloud Image Mirrors]
    Service -->|SSH| VM[New VM]
    VM -->|curl /sh/os_version.sh| Gin
  1. graph TB
  2. Client -->|HTTP / SSE| Gin[Gin Router + CORS]
  3. Gin --> Handler[Handler Layer<br/>ALLOW_IPS / state checks]
  4. Handler --> Util[Util<br/>VM / node lookup]
  5. Handler --> Service[Service Layer]
  6. Util -->|pvesh| PVE[(Proxmox Cluster API)]
  7. Util --> Disabled[.go_qemu_disabled]
  8. Service -->|qm / pvesh / pvesm| Main[Main Node]
  9. Service -->|SSH root@NODE_x + qm| Remote[Remote Node]
  10. Service -->|HTTP| Mirror[Official Cloud Image Mirrors]
  11. Service -->|SSH| VM[New VM]
  12. VM -->|curl /sh/os_version.sh| Gin

Layers


LayerLocationResponsibility
Entrycmd/api/main.goLoads .env, checks PORT / GATEWAY, mounts the /sh static dir, starts Gin
Configinternal/configCORS middleware and /api route registration
Handlerinternal/handlerParses params, runs ALLOW_IPS and VM state pre-checks, picks a plain text / JSON / SSE response
Serviceinternal/serviceEvery qm / pvesh / pvesm / ssh call, the install pipeline, resource allocation, SSE push
Utilinternal/utilCluster VM / node lookups, the disabled list, ALLOW_IPS matching
Modelinternal/modelRequest, response, and SSE structures

Cross-Cutting Principles


  • Proxmox CLI as the API: no Proxmox HTTP API calls and no stored tokens; every operation is qm / pvesh / pvesm on the main node, or qm over SSH on another node
  • No database: cluster state is read live from pvesh get /cluster/resources and /etc/pve/nodes; the only local data are three State Files
  • Long operations always stream: install, start, reboot, and migration report each step over SSE; short operations reply ok
  • The VMID decides the network: the last IP octet equals the VMID, so there is no DHCP or IP table; see VMID and IP Allocation

Position Among Go Proxmox Tools


Most Go tooling for Proxmox VE works through the Proxmox VE HTTP API. Telmate/proxmox-api-go is a Go client library for that API, and Telmate/terraform-provider-proxmox builds its Terraform provider on top of it. bpg/terraform-provider-proxmox is a Terraform / OpenTofu provider that also runs nearly every operation through the Proxmox VE API with an API token, using SSH only for a few operations. Those tools describe VMs from your own machine or CI and apply them to the cluster.
QemuRun-pve sits on the cluster's main node instead and exposes its own small REST API: one POST /api/vm/install picks a free VMID and IP, downloads the official cloud image, runs qm create and cloud-init locally, and streams each stage over SSE, with no Proxmox API token to store.

Further Reading


Module internals, sequence diagrams, and the VM state machine live in doc/architecture.md.
中文