Proxmoxve Laravel Package

Technical Evaluation

What it is: zzantares/proxmoxve is a community, MIT-licensed PHP client that wraps the Proxmox VE REST API (/api2/json). It is framework-agnostic with a thin Laravel service provider/facade carried from its Laravel 5-era origins. ~177 stars, last tagged release Feb 2023, PHP 5.5+ lineage.

Architecture fit: Treat this as commodity plumbing, not a platform component. If Proxmox is the substrate for a provisioning/orchestration product, this library only gets you HTTP transport plus endpoint sugar — VMID allocation, idempotency, task state machines, IPAM, cloud-init injection, and reconciliation remain ours to build. That is acceptable: it is a 200–400 LOC dependency replacing maybe 2–3 weeks of hand-rolled Guzzle work. It is not acceptable as the boundary of our domain model, because its response objects are arrays/stdClass and will leak into business logic if unguarded.

Integration feasibility: High. Composer install, no daemon, no schema, no queue worker, no extra infrastructure. The real cost is governance, not engineering.

Technical risk (ranked):

• Bus factor of one. No release in ~2 years; PVE 8.x API surface (SDN, newer task semantics, API token scopes) is unlikely to be fully covered.
• Authentication model. Older releases default to ticket + CSRF-token auth (PVEAPITicket/PVEACSREFPrevention), which requires a stored password and a 2FA-exempt realm. API-token support must be verified before we commit; if absent, we patch the fork. This is the single largest security decision in the evaluation.
• Error semantics. Sparse exception hierarchy — distinguishing transient (pvedaemon restart, quorum loss) from permanent (invalid VMID, permission denied) failures likely requires parsing raw response bodies. No retry/backoff.
• Dependency drift. Guzzle and illuminate/* constraints may conflict with a current Laravel skeleton; may need --ignore-platform-reqs-style workarounds or a fork.
• Testability. No fixtures or mock server shipped; we must build a fake against the interface, not the package.

Key questions:

1. Does the pinned version support API tokens with privilege separation, and does it handle ticket expiry/refresh?
2. What are its Guzzle and Laravel version constraints against our target stack (PHP 8.2/8.3, Laravel 10/11)?
3. Has anyone exercised it against PVE 8.x, and is there a fork we should track instead?
4. Can we accept owning this code (fork + patch) for the product's lifetime?
5. Does the licensing/attribution model create any obligations for a commercial distribution? (MIT — no, but confirm vendored notices.)

Integration Approach

Stack fit: PHP 8.1+, Laravel 10/11, Guzzle 7. Register as a container singleton with a published config file (host, port, token_id, secret, realm, verify_tls). Secrets via environment/Vault, never committed; use a dedicated API token bound to a service role scoped to a resource pool (PVEVMAdmin + PVEVMAllocate + Datastore.AllocateSpace as needed) — never root@pam.

Adapter, not direct usage. Define an internal ProxmoxGateway interface (listNodes, listGuests, cloneVm, start/stop, taskStatus). Implement it once with this package. Application and domain code depend only on the interface. This caps the blast radius if we later swap to raw Guzzle, a maintained fork, or the Python proxmoxer sidecar. Ban ZzAntares\ProxmoxVE\* imports outside the adapter namespace and enforce with a static-analysis rule.

Migration path (incremental, reversible):

1. Spike (1 week): adapter skeleton + auth proof against a lab cluster; validate token auth and PVE 8.x.
2. Read-only: node inventory, guest status, storage capacity. No mutations. Safe to ship behind a flag.
3. Lifecycle on a non-production pool: start/stop/reboot, snapshot, task polling via queued jobs.
4. Provisioning: clone-from-template with idempotency keys, VMID reservation, cloud-init, IPAM handoff.
5. Destructive ops: destroy, disk resize, migration — each gated behind its own feature flag and an approval/audit trail.

Sequencing rules: never call the package from a web request handler for long operations; always dispatch to a queue job that submits the task and returns the UPID, then poll with exponential backoff. Persist UPIDs so a worker restart doesn't orphan state. Version pin to an exact tag and commit hash, and mirror the repository internally.

Compatibility: maintain an explicit matrix (package version × PVE 7.4 / 8.x × PHP × Laravel) and a lab cluster that runs the highest PVE version we support. Treat PVE minor upgrades as a change-management event.

Operational Impact

Maintenance: Assume we own it. Budget roughly 1 developer-day per quarter for fork upkeep, dependency bumps, and PVE API drift, plus a defined owner. Vendor the source into a private mirror with a patch branch; do not rely on upstream responsiveness. Track upstream issues for security-relevant reports.

Support: No vendor, no SLA, community issues only. The escalation path terminates with our own engineers, so the runbook must cover Proxmox-side operations — this is an infrastructure-knowledge dependency, not a library-support dependency.

Scaling: All operations are synchronous HTTP against pvedaemon, with long-running actions surfaced as async tasks. Two constraints dominate:

• API-level: polling every task at high frequency is the classic failure. Poll with backoff (1s → 10s → 30s cap), use task-status reads rather than full resource listings, and cap concurrency per cluster (start conservatively at 3–5 in-flight mutating operations per node).
• Cluster-level: quorum-sensitive operations and storage contention are the real ceiling, not PHP. Enforce per-cluster rate limits and queue partitioning; one misbehaving tenant shouldn't saturate the API for everyone.

Failure modes to design for:

• Auth/ticket expiry and CSRF rejections surfacing as opaque 401s → central token refresh, surface as a distinct alert class.
• pvedaemon restart or node offline returning 5xx/595 with no useful body → classify as transient with bounded retries and jitter; fail the job cleanly, don't retry indefinitely.
• Task timeouts on clone/migrate (10+ minutes is normal) → durable task records, reconciliation sweeps that adopt orphaned UPIDs on worker restart.
• Partial provisioning leaving orphaned VMs, disks, or reserved VMIDs → compensating cleanup job keyed on a provisioning correlation ID.
• Duplicate VMID races from concurrent creates → reservation table with a unique constraint before submission.
• Storage exhaustion mid-clone → pre-flight capacity check, not post-hoc error handling.

Observability: Log every API call with method, endpoint, duration, HTTP status, and correlation ID; emit task UPIDs into traces; alert on auth failure rate, task failure rate, and task duration p95.

Ramp-up: A competent PHP/Laravel developer is productive against the adapter in 1–2 days — the API is small. Operational fluency is the longer curve: VMID allocation, pools and role inheritance, storage content types, templates vs. clones, and cloud-init semantics take 1–2 weeks. On-call rotation needs a written Proxmox runbook, not the package README. Plan for one team member to become the designated Proxmox owner; the package itself does not carry that knowledge.