go-pve-qemu — Technical Documentation

Back to README

Table of Contents

• Prerequisites
• Installation
• Configuration
• Usage
• API Reference
• SSE Event Format
• Install Pipeline Stages

Prerequisites

• Go ≥ 1.20 installed on the Proxmox main node
• Standard Proxmox VE CLI tools qm and pvesh available
• Key-based SSH access (no passphrase) from the main node to all remote nodes
• Network gateway configured so that VMID equals the last IP octet (e.g. 192.168.0.X where X = VMID)
• Target Proxmox storage pool (ASSIGN_STORAGE) must exist and be active

Installation

Build from Source

git clone https://github.com/pardnchiu/go-pve-qemu.git
cd go-pve-qemu
cp .env.example .env
# edit .env (see Configuration section)
go build -o go-pve-qemu ./cmd/api
./go-pve-qemu

The server prints all registered routes on startup and listens on the configured PORT.

Systemd Service (optional)

[Unit]
Description=go-pve-qemu API
After=network.target

[Service]
WorkingDirectory=/opt/go-pve-qemu
ExecStart=/opt/go-pve-qemu/go-pve-qemu
Restart=on-failure
EnvironmentFile=/opt/go-pve-qemu/.env

[Install]
WantedBy=multi-user.target

Configuration

All configuration is via environment variables (loaded from .env on startup via godotenv).

Required

Optional

Example .env

PORT=8080
GATEWAY=192.168.0.1
MAIN_NODE=pve1
NODE_pve1=192.168.0.11
NODE_pve2=192.168.0.12
NODE_pve3=192.168.0.13
ASSIGN_STORAGE=local-zfs
ASSIGN_IP_START=100
ASSIGN_IP_END=254
ALLOW_IPS=0.0.0.0
VM_MAX_CPU=32
VM_MAX_RAM=32768
VM_MAX_DISK=64
VM_BALLOON_MIN=2048
VM_ROOT_PASSWORD=

Usage

Health Check

curl http://localhost:8080/api/health
# Response: ok

Provision a VM

A single API call provisions a complete VM end-to-end:

curl -X POST http://localhost:8080/api/vm/install \
  -H "Content-Type: application/json" \
  -d '{
    "os": "ubuntu",
    "version": "22.04",
    "name": "web-01",
    "cpu": 2,
    "ram": 4096,
    "disk": "40G",
    "user": "deploy",
    "passwd": "s3cr3t"
  }'

The response is an SSE stream showing real-time progress and elapsed time for each stage.

List VMs

curl http://localhost:8080/api/vm/list

Returns cluster-wide VM inventory and per-node resource utilization.

Manage VM Lifecycle

# Start VM (SSE stream until SSH ready)
curl -X POST http://localhost:8080/api/vm/101/start

# Graceful shutdown
curl -X POST http://localhost:8080/api/vm/101/shutdown

# Force stop
curl -X POST http://localhost:8080/api/vm/101/stop

# Reboot (SSE stream)
curl -X POST http://localhost:8080/api/vm/101/reboot

# Destroy VM
curl -X POST http://localhost:8080/api/vm/101/destroy

Adjust Resources

# Set vCPU
curl -X POST http://localhost:8080/api/vm/101/set/cpu \
  -H "Content-Type: application/json" \
  -d '{"cpu": 4}'

# Set memory
curl -X POST http://localhost:8080/api/vm/101/set/memory \
  -H "Content-Type: application/json" \
  -d '{"memory": 8192}'

# Expand disk
curl -X POST http://localhost:8080/api/vm/101/set/disk \
  -H "Content-Type: application/json" \
  -d '{"disk": "10G"}'

Node Migration

curl -X POST http://localhost:8080/api/vm/101/set/node \
  -H "Content-Type: application/json" \
  -d '{"node": "pve2"}'

The response is an SSE stream showing real-time migration progress.

API Reference

All endpoints are prefixed with /api.

Commands

POST /api/vm/install Request Parameters

POST /api/vm/:id/set/cpu Request Body

{ "cpu": 4 }

Valid range: 1–32 (further capped by VM_MAX_CPU).

POST /api/vm/:id/set/memory Request Body

{ "memory": 8192 }

Value in MB. Minimum 512, maximum VM_MAX_RAM.

POST /api/vm/:id/set/disk Request Body

{ "disk": "10G" }

Expands disk by the specified amount. Disk shrinking is not supported.

POST /api/vm/:id/set/node Request Body

{ "node": "pve2" }

Migrates the VM to another cluster node with local disk transfer.

SSE Event Format

All SSE endpoints emit data: lines with JSON payloads.

data: {"step":"<stage>","status":"<status>","message":"<text>","vm_id":<id>,"ip":"<ip>"}

Install Pipeline SSE Example

data: {"step":"preparation > checking VMID","status":"processing","message":"[*] start VM installation"}
data: {"step":"preparation > checking VMID","status":"success","message":"[+] auto-assigned VMID: 101 (0.02s)"}
data: {"step":"preparation > assigning IP","status":"success","message":"[+] assigned IP: 192.168.0.101/24 (0.00s)"}
data: {"step":"OS preparation > downloading OS image","status":"processing","message":"[*] start downloading OS image"}
data: {"step":"OS preparation > downloading OS image","status":"success","message":"[+] completed OS image download (18.34s)"}
data: {"step":"VM creation > creating VM","status":"success","message":"[+] VM created successfully (2.45s)"}
data: {"step":"VM creation > importing disk image","status":"success","message":"[+] disk image imported successfully (8.12s)"}
data: {"step":"VM initialization > initializing configuration","status":"success","message":"[+] VM initialized successfully (1.03s)"}
data: {"step":"VM initialization > waiting for ready","status":"processing","message":"[*] VM starting"}
data: {"step":"VM initialization > SSH initialization","status":"success","message":"[+] SSH initialization completed (5.21s)"}
data: {"step":"VM initialization > finalizing","status":"success","message":"[+] VM installation completed in 67.83s"}
data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 101"}
data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.101"}
data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: deploy"}

Install Pipeline Stages

The POST /api/vm/install pipeline executes the following stages in order:

©️ 2025 邱敬幃 Pardn Chiu