Skip to content

feat: add Proxmox VE machine engine#31

Open
bdegeeter wants to merge 3 commits into
spectrocloud:masterfrom
bdegeeter:pr/proxmox-engine
Open

feat: add Proxmox VE machine engine#31
bdegeeter wants to merge 3 commits into
spectrocloud:masterfrom
bdegeeter:pr/proxmox-engine

Conversation

@bdegeeter

Copy link
Copy Markdown
Contributor

Summary

Add a Proxmox VE machine engine that creates and manages QEMU virtual machines through the Proxmox API.

The backend integrates with Peg's existing machine lifecycle and supports YAML configuration, CLI and environment overrides, SSH commands and file transfer, disks, CD media, networking, monitoring, cleanup, and VNC screenshots.

Features

  • API-token or username/password authentication.
  • Validation requiring exactly one complete authentication method.
  • TLS certificate verification by default.
  • Explicit insecureTLS option for trusted environments using self-signed certificates.
  • VM creation, start, stop, deletion, and partial-creation rollback.
  • Regular Linux bridge and Proxmox SDN networking.
  • Optional custom QEMU arguments when using username/password authentication.
  • Disk creation with validated sizes and unused SCSI-slot selection.
  • Local ISO transfer.
  • URL-based ISO provisioning.
  • Existing Proxmox storage ISO references.
  • Peg-owned, content-addressed ISO names to avoid deleting unrelated files.
  • Bounded lifecycle and monitoring operations.
  • Transient monitoring failure tolerance.
  • VNC screenshot capture with validated RFB bounds and timeout-aware handshakes.
  • CLI flags, environment variables, example configuration, and README documentation.

The implementation uses github.com/luthermonson/go-proxmox v0.3.2 and retains the repository's Go 1.24 toolchain.

Additional generator fixes

  • Allow specs without a Ginkgo label instead of constructing an empty label.
  • Write assertion command output to GinkgoWriter, allowing it to be displayed with Ginkgo writer-output options such as --always-emit-writer.

Safety and failure handling

  • A partially created VM is rolled back if a later creation or start step fails.
  • API operations use bounded contexts.
  • Monitoring does not invoke OnFailure with a nil machine.
  • Disk sizes are validated and rounded upward from MB to GiB.
  • ISO collisions are reported instead of deleting an unrelated matching file.
  • The temporary ISO server exposes only the intended file and shuts down cleanly.
  • API URLs are parsed with net/url, including IPv6 and custom ports.
  • Custom QEMU arguments require username/password authentication because Proxmox restricts the API-token path for that setting.

Validation

The following checks pass with Go 1.24.2:

  • go test ./...
  • go test -race ./...
  • go vet ./...
  • git diff --check

Automated tests cover:

  • Configuration and authentication validation.
  • VM creation, start, stop, deletion, and rollback.
  • VM options and API failures.
  • Disk sizing and SCSI-slot selection.
  • Local, URL, and storage-reference ISO modes.
  • ISO ownership and collision handling.
  • Monitoring behavior and transient errors.
  • RFB authentication, framebuffer conversion, malformed input, and timeouts.

Manual Proxmox validation

The backend was exercised against a live Proxmox environment using:

  • Username/password authentication.
  • Explicit insecure TLS for a self-signed lab certificate.
  • Local ISO transfer and subsequent cache reuse.
  • A regular vmbr0 Linux bridge.
  • VM creation and startup.
  • SSH connection and assertion execution.
  • VM stop and deletion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant