Core Concepts

The service combines deterministic Proxmox commands with streamed progress for VM operations.

VM identity and IP allocation

A provisioning request may provide id; otherwise the installation flow allocates an available VMID. The service derives the guest address from GATEWAY: it uses the first three IPv4 octets and the VMID as the final octet, then assigns a /24 address. Ensure the configured VMID range and network design are compatible.

Resource normalization

Before creation, the service applies defaults and limits:

initConfig also derives the default SSH user from the selected OS (debian, ubuntu, or rockylinux) and appends the VM ID to a supplied name.

Cloud image and cloud-init

The install flow resolves an OS image for the requested distribution and version, validates its URL, and downloads it only when it is not already cached. It creates the VM, imports the image disk, and applies the cloud-init and boot configuration before the first boot.

SSH readiness and initialization

After starting a VM, the service polls for SSH readiness. Once reachable, it runs OS-specific initialization over SSH, reboots the VM, and checks reachability again. A failed readiness check is reported through the SSE stream.

SSE progress

Install, start, reboot, and node migration are long-running actions. Their handlers configure text/event-stream; Service.SSE writes events in this shape:

data: {"step":"<stage>","status":"processing|success|error","message":"<detail>"}

Clients should keep the connection open and render events in order. curl -N is convenient for local inspection.

CPU compatibility

GetClusterCPUType queries Proxmox node CPU flags, derives the lowest compatible x86-64 level shared by the cluster, and caches the result in .go_qemu_cpu_type. The cache avoids repeating the cluster scan during later provisioning requests.

Lifecycle operations

The API supports start, force stop, ACPI shutdown, reboot, destroy, CPU/memory/disk adjustment, and node migration. Operations locate the VM across the cluster and then use local or SSH-dispatched qm commands.

Continue with Configuration for deployment controls or API Reference for request details.