v0.1.7

pardnchiu/QemuRun-pve

Last updated

NoteThis README was generated by SKILL, get the ZH version from here.



ONE API CALL FROM CLOUD IMAGE TO SSH-READY VM ON PROXMOX VE!


ReleaseLicense




A Go Proxmox VE REST API with SSE-streamed provisioning, concurrent VMID/IP allocation, and transparent multi-node dispatch

Table of Contents



Features


git clone https://github.com/pardnchiu/QemuRun-pve.git · Documentation

  • One-Call Provisioning — A single POST downloads the official cloud image, creates the VM, imports the disk, injects cloud-init, and runs the OS init script, streaming every stage and its duration over Server-Sent Events.
  • VMID-as-IP Concurrent Allocation — Probes the configured range from both ends in parallel, skipping IDs taken by config files, qm config, or a live SSH port, and uses the first free number as both VMID and last IP octet.
  • Cluster CPU Baseline Detection — Reads CPU flags from every node, picks the lowest common x86-64 level, and caches it so VMs stay migratable across the whole cluster.
  • Transparent Multi-Node Dispatch — Runs qm locally for VMs on the main node and over SSH for every other node, so callers never deal with cluster topology, including live migration with local disks.
  • Three-Layer Access Guard — CORS admits only same-private-subnet origins, mutating calls require an ALLOW_IPS match, and a disabled list locks specific VMIDs out of API control.

Architecture


Full Architecture

graph LR
    Client -->|HTTP / SSE| Handler
    Handler --> Service
    Service -->|qm / pvesh| Main[Main Node]
    Service -->|SSH + qm| Remote[Remote Node]
    Service -->|download| Image[Official Cloud Image]
    Main -->|cloud-init| VM
    VM -->|curl /sh| Script[OS Init Script]
  1. graph LR
  2. Client -->|HTTP / SSE| Handler
  3. Handler --> Service
  4. Service -->|qm / pvesh| Main[Main Node]
  5. Service -->|SSH + qm| Remote[Remote Node]
  6. Service -->|download| Image[Official Cloud Image]
  7. Main -->|cloud-init| VM
  8. VM -->|curl /sh| Script[OS Init Script]

License


This project is licensed under the AGPL-3.0 LICENSE.

Author


Just open an issue to share an idea.
QemuRun-pve contributors


©️ 2025 邱敬幃 Pardn Chiu
中文