# pardnchiu/go-pve-qemu

> Self-hosted Go REST API service for Proxmox VE VM automation by Pardn Chiu (邱敬幃): one-call cloud-init provisioning over SSE, VMID/IP allocation, node dispatch.

Maintained by Pardn Chiu (pardnchiu), Pardn Co., Ltd. Source: https://github.com/pardnchiu/go-pve-qemu

Full text in one file: [English](https://go-pve-qemu.pardn.io/llms-full.txt) · [中文](https://go-pve-qemu.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://go-pve-qemu.pardn.io/index.md): Self-hosted Go REST API service for Proxmox VE VM automation by Pardn Chiu (邱敬幃): one-call cloud-init provisioning over SSE, VMID/IP allocation, node dispatch.
- [Getting Started](https://go-pve-qemu.pardn.io/getting-started.md): Prerequisites, source build, .env setup, and a first SSE-streamed VM install with go-pve-qemu on a Proxmox VE main node.
- [Deployment](https://go-pve-qemu.pardn.io/deployment.md): Run go-pve-qemu from a GitHub release tarball or as a root systemd service, keeping sh/, .env, and state files in the working directory.

## Configuration

- [Environment Variables](https://go-pve-qemu.pardn.io/configuration.md): Every go-pve-qemu environment variable: required node, gateway, storage, and ALLOW_IPS settings plus VMID range, resource caps, and ballooning.
- [State Files](https://go-pve-qemu.pardn.io/state-files.md): The .go_qemu_disabled lock list, .go_qemu_pubkey_admin key file, and .go_qemu_cpu_type cache that go-pve-qemu reads from its working directory.

## Concepts

- [Architecture](https://go-pve-qemu.pardn.io/architecture.md): System overview of go-pve-qemu: Gin router, handler, service, and util layers mapped to qm, pvesh, SSH, and cloud image mirrors.
- [Core Concepts](https://go-pve-qemu.pardn.io/core-concepts.md): The five ideas behind go-pve-qemu (VMID equals IP octet, staged provisioning, CPU baseline, node dispatch, layered access) with links to each topic.

## Provisioning

- [Provisioning Pipeline](https://go-pve-qemu.pardn.io/provisioning-pipeline.md): Stage-by-stage walkthrough of POST /api/vm/install: clamping, image download, qm create, cloud-init, SSH init script, reboot, and failure cleanup.
- [VMID and IP Allocation](https://go-pve-qemu.pardn.io/vmid-ip-allocation.md): How go-pve-qemu probes the VMID range from both ends with 10 concurrent workers and uses the first free number as the VM's last IP octet.
- [CPU Baseline](https://go-pve-qemu.pardn.io/cpu-baseline.md): How go-pve-qemu reads CPU flags from every Proxmox node, picks the lowest common x86-64 level, and caches it for qm create.
- [OS Init Scripts](https://go-pve-qemu.pardn.io/os-init-scripts.md): The sh/<os>_<version>.sh scripts new VMs download from go-pve-qemu: supported Debian, Ubuntu, and Rocky Linux versions and what each script changes.

## Cluster

- [Multi-Node Dispatch](https://go-pve-qemu.pardn.io/multi-node-dispatch.md): How go-pve-qemu locates a VM's node from /etc/pve/nodes and runs qm locally on the main node or over root SSH on every other node.
- [Access Control](https://go-pve-qemu.pardn.io/access-control.md): go-pve-qemu's three guards: private-subnet CORS, the ALLOW_IPS client whitelist for mutating calls, and per-VM state and lock checks.

## Reference

- [API Reference](https://go-pve-qemu.pardn.io/api-reference.md): Every go-pve-qemu REST endpoint at a glance: method, path, response type, ALLOW_IPS requirement, and the VM state it expects.
- [Install Endpoint](https://go-pve-qemu.pardn.io/api-install.md): Request fields, defaults, clamping rules, and SSE output of POST /api/vm/install for creating Debian, Ubuntu, and Rocky Linux VMs.
- [Lifecycle Endpoints](https://go-pve-qemu.pardn.io/api-lifecycle.md): Start, reboot, shutdown, stop, and destroy endpoints of go-pve-qemu, with required VM state, response format, and SSH readiness waits.
- [Resource Endpoints](https://go-pve-qemu.pardn.io/api-resources.md): Change vCPU, memory with ballooning, disk size, and node placement of a stopped VM through go-pve-qemu's set endpoints.
- [Query Endpoints](https://go-pve-qemu.pardn.io/api-query.md): Health check, single VM status, and the cluster-wide VM list with node allocation percentages returned by go-pve-qemu.
- [SSE Events](https://go-pve-qemu.pardn.io/sse-events.md): Event format, status values, message prefixes, and a Go client example for go-pve-qemu's Server-Sent Events progress streams.

## 中文文件

- [首頁](https://go-pve-qemu.pardn.io/zh/index.md): 邱敬幃（Pardn Chiu）的自架 Proxmox VE 虛擬機自動化 REST API 服務：一次呼叫完成 cloud-init 佈建，SSE 回報。
- [快速開始](https://go-pve-qemu.pardn.io/zh/getting-started.md): 在 Proxmox VE 主節點上準備環境、自原始碼建置 go-pve-qemu，並完成第一台 VM 佈建。
- [部署](https://go-pve-qemu.pardn.io/zh/deployment.md): 以 GitHub Release 執行檔或 systemd 常駐執行 go-pve-qemu，並維持工作目錄中的 sh/、.env 與狀態檔。
- [環境變數](https://go-pve-qemu.pardn.io/zh/configuration.md): go-pve-qemu 全部環境變數：節點、網關、儲存池、ALLOW_IPS 必填項，以及 VMID 區間、資源上限與 Balloon。
- [狀態檔](https://go-pve-qemu.pardn.io/zh/state-files.md): go-pve-qemu 工作目錄中的狀態檔：停用清單 .go_qemu_disabled、管理者公鑰與 CPU 類型快取。
- [架構](https://go-pve-qemu.pardn.io/zh/architecture.md): go-pve-qemu 系統概覽：Gin 路由、Handler、Service、Util 各層與 qm、pvesh、SSH、映像站的對應關係。
- [核心概念](https://go-pve-qemu.pardn.io/zh/core-concepts.md): go-pve-qemu 的五個核心設計：VMID 即 IP、分段佈建、CPU 基準、節點調度、分層存取，並連到各主題頁。
- [佈建流程](https://go-pve-qemu.pardn.io/zh/provisioning-pipeline.md): POST /api/vm/install 逐階段說明：上下限、映像下載、qm create、cloud-init、初始化腳本、重開與失敗清除。
- [VMID 與 IP 配置](https://go-pve-qemu.pardn.io/zh/vmid-ip-allocation.md): go-pve-qemu 如何以 10 個並行 worker 從區間兩端探測 VMID，並把第一個可用編號作為 IP 末段。
- [CPU 基準](https://go-pve-qemu.pardn.io/zh/cpu-baseline.md): go-pve-qemu 如何讀取每個節點的 CPU flags、取全叢集最低 x86-64 等級並快取給 qm create 使用。
- [OS 初始化腳本](https://go-pve-qemu.pardn.io/zh/os-init-scripts.md): 新 VM 下載執行的 sh/<os>_<version>.sh：支援的 Debian、Ubuntu、Rocky Linux 版本與變更內容。
- [多節點調度](https://go-pve-qemu.pardn.io/zh/multi-node-dispatch.md): go-pve-qemu 如何從 /etc/pve/nodes 找出 VM 所在節點，於主節點直接執行 qm，其他節點經 root SSH 轉送。
- [存取控制](https://go-pve-qemu.pardn.io/zh/access-control.md): go-pve-qemu 的三層防護：私有子網 CORS、寫入操作的 ALLOW_IPS 白名單，以及每台 VM 的狀態與鎖定檢查。
- [API 參考](https://go-pve-qemu.pardn.io/zh/api-reference.md): go-pve-qemu 全部 REST 端點一覽：方法、路徑、回應型態、ALLOW_IPS 要求與預期的 VM 狀態。
- [建立 VM 端點](https://go-pve-qemu.pardn.io/zh/api-install.md): POST /api/vm/install 的請求欄位、預設值、上下限規則與 SSE 輸出，用於建立 Debian、Ubuntu、Rocky Linux VM。
- [生命週期端點](https://go-pve-qemu.pardn.io/zh/api-lifecycle.md): go-pve-qemu 的 start、reboot、shutdown、stop、destroy 端點：狀態要求、回應格式與 SSH 就緒等待。
- [資源調整端點](https://go-pve-qemu.pardn.io/zh/api-resources.md): 透過 go-pve-qemu 的 set 端點調整已停止 VM 的 vCPU、記憶體與 Balloon、磁碟大小與所在節點。
- [查詢端點](https://go-pve-qemu.pardn.io/zh/api-query.md): go-pve-qemu 的健康檢查、單台 VM 狀態，以及含節點配置百分比的叢集 VM 清單。
- [SSE 事件](https://go-pve-qemu.pardn.io/zh/sse-events.md): go-pve-qemu Server-Sent Events 進度串流的事件格式、狀態值、訊息前綴與 Go 客戶端範例。

## Optional

- [Release Notes](https://go-pve-qemu.pardn.io/released/index.md): pardnchiu/go-pve-qemu changelog by version