v0.1.7

Provisioning Pipeline

Last updated


This page walks through what POST /api/vm/install does, stage by stage, from the request to an SSH-ready VM.

Stage Overview


Each SSE event's step field reads <stage> > <step>.
StageStepAction
preparationchecking VMIDRuns VMID allocation when id is omitted; an explicit id is used as is, without an availability check
assigning IPFirst three octets of GATEWAY + VMID, with /24
validating CPU and RAMCPU ≤ 0 → 1; above VM_MAX_CPU is clamped. RAM < 512 → 512; above VM_MAX_RAM is clamped
validating disk sizeParses the number after stripping a trailing G; < 16 → 16G; ≥ VM_MAX_DISK → the cap
setting default config valuesAppends -<vmid> to the name, fills the default user and password
checking storage poolpvesm status confirms ASSIGN_STORAGE is active and of type dir / zfspool / lvmthin / nfs
OS preparationgetting OS imageResolves the image URL from os / version
validating OS image URLHEAD request must return 200 within 15 seconds
downloading OS imageDownloads to /tmp; skipped when the file already exists (using OS image)
SSH preparationchecking SSH keyGenerates a key with ssh-keygen -t ed25519 when the main node has none
VM creationcreating VMqm create with the cluster baseline CPU type, or kvm64 when detection fails
importing disk imageqm importdisk into ASSIGN_STORAGE
VM initializationinitializing configurationqm set in order: SSH keys, password, --ciupgrade 0, OS tag, scsi0, cloud-init disk, boot order; qm resize to the target size (3 attempts, 5 seconds apart); finally ipconfig0
migrating VMRuns qm migrate --with-local-disks only when the request sets node
waiting for readyAfter boot, tries SSH every 5 seconds, up to 60 times
SSH initializationRuns the OS init script inside the VM and relays each output line as SSE
rebooting VMqm reboot, then waits for SSH again
finalizingReports total duration, VMID, IP, and user

qm create Arguments


ArgumentValue
--coresRequested cpu (after clamping)
--cpuCluster baseline, or kvm64
--memoryRequested ram (after clamping)
--scsihwvirtio-scsi-pci
--ostypel26
--agent1
--net0virtio,bridge=vmbr0
--serial0socket
--numa / --balloonPer the ballooning rule

--ciupgrade 0 turns off cloud-init's boot-time package upgrade so it does not fight the init script for the package lock.

Failure Handling


Failure pointHandling
Preparation, image, SSH key, qm createSends an error event and stops; no VM is left (not created yet, or creation failed)
importing disk image, initializing configuration, SSH initializationForce-stops and runs qm destroy --purge --skiplock to remove the partial VM
Migrate, start, or reboot command failsStops immediately; the VM stays in the cluster
SSH wait times outSends an error event and stops; the VM stays so you can debug it on the node

Success or failure, the handler always ends with event: close.

Image Cache


Downloads are stored in /tmp under version-specific names (e.g. /tmp/debian-12-generic-amd64.qcow2) and reused by later installs of the same version. Delete the file manually to pick up a newer upstream image.
中文