Automate Proxmox with one clean REST API

Introduction

Proxmox VE's native API is a powerful tool, but it can feel low-level and cumbersome due to its ticket-based nature. In this post, we’ll explore how NexoVirt's token-authenticated REST API simplifies this process. With a consistent response envelope and per-token host scoping, you can easily script the entire guest lifecycle from one endpoint.

Async Provisioning Model

NexoVirt's API follows an asynchronous provisioning model. When you initiate an action (like creating a VM), the API immediately returns a response indicating that the action is queued, along with a job_id for polling the job status. This means you can track the progress and ensure actions complete successfully. This shared executor model makes the API behave identically to the web wizard, streamlining your automation efforts.

In contrast, the raw Proxmox pvesh/ticket API often requires a more complex approach to handle asynchronous tasks and state management.

Proxmox REST API Examples

Let’s dive into some practical examples using curl commands.

Create a Snapshot

To create a snapshot:

curl -X POST 'https://your-nexovirt-instance/api/v1/guests/{guest_id}/snapshots' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "snapshot-name"}'

To roll back to a snapshot:

curl -X POST 'https://your-nexovirt-instance/api/v1/guests/{guest_id}/snapshots/{snapshot_id}/rollback' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

To delete a snapshot:

curl -X DELETE 'https://your-nexovirt-instance/api/v1/guests/{guest_id}/snapshots/{snapshot_id}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Add a Per-Guest Firewall Rule

To add a firewall rule:

curl -X POST 'https://your-nexovirt-instance/api/v1/guests/{guest_id}/firewall/rules' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"action": "ACCEPT", "direction": "IN", "interface": "vmbr0", "source": "0.0.0.0/0", "dest": "0.0.0.0/0"}'

Set NAT and Port-Forward

To set up NAT with port-forwarding:

curl -X POST 'https://your-nexovirt-instance/api/v1/guests/{guest_id}/nat' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"public_ip": "YOUR_PUBLIC_IP", "private_ip": "YOUR_PRIVATE_IP", "port": 80}'

Resize a Guest

To resize CPU cores, memory, and disk:

curl -X PUT 'https://your-nexovirt-instance/api/v1/guests/{guest_id}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"cores": 4, "memory": 8192, "disk": 50}'

List and Acknowledge Alerts

To list alerts:

curl -X GET 'https://your-nexovirt-instance/api/v1/alerts' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

To acknowledge an alert:

curl -X POST 'https://your-nexovirt-instance/api/v1/alerts/{alert_id}/acknowledge' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Grant a Customer an IP from a Pool

To grant an IP address:

curl -X POST 'https://your-nexovirt-instance/api/v1/ip-pools/{pool_id}/assign' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"customer_id": "CUSTOMER_ID"}'

Conclusion

NexoVirt's REST API empowers you to automate your Proxmox VE environment effectively. With a few simple commands, you can manage snapshots, firewall rules, NAT configurations, resource resizing, alerts, and IP assignments seamlessly. For more information, check out our REST API docs, explore the Clean REST API feature, and discover the Provisioning feature.