Automating Proxmox VM Deletion with Terraform, Curl, and JQ

Fixing Proxmox Terraform Deletes with curl + jq

The Proxmox Terraform provider cannot natively delete a running virtual machine or container, leading to immediate pipeline failures during resource destruction. This limitation forces engineers to manually intervene or script pre-deletion checks to ensure a stopped state before Terraform execution.

Why This Matters

While Infrastructure as Code tools like Terraform aim for declarative state management, the technical reality often involves provider-specific limitations that do not account for active resource locks. In push-based deployments like GitHub Actions, a single rejected API call from Proxmox halts the entire automation cycle, highlighting the gap between high-level abstraction and low-level API enforcement.

Key Insights

• The Proxmox API rejects destroy requests for active QEMU/LXC resources, necessitating a state transition to stopped prior to deletion.
• Status validation is achieved by querying the status/current endpoint and parsing the .data.status field using jq as of 2026.
• Persistent environment variables like TF_VAR_proxmox_api_token_secret are required for PVEAPIToken authentication within automation runners.
• The curl -sk flag is utilized in homelab environments to bypass SSL verification for local Proxmox nodes during API interactions.

Working Examples

Logic to query VM status via Proxmox API and issue a stop command if the resource is currently running.

STATUS=$(curl -sk -H "$PVE_AUTH" "${PVE_API}/nodes/${PVE_NODE}/qemu/${VMID}/status/current" | jq -r '.data.status')
if [ "$STATUS" = "running" ]; then
echo "Stopping VM $VMID..."
curl -sk -X POST -H "$PVE_AUTH" "${PVE_API}/nodes/${PVE_NODE}/qemu/${VMID}/status/stop"
fi

Setting persistent environment variables for Proxmox API authentication on Windows.

setx TF_VAR_proxmox_api_url "https://YOUR-IP:8006/api2/json"
setx TF_VAR_proxmox_api_token_id "user@pam!token"
setx TF_VAR_proxmox_api_token_secret "your-secret"

Practical Applications

• GitHub Actions runners automate homelab updates by stopping VMs before Terraform apply or destroy cycles to prevent pipeline blockage.
• Attempting to delete resources without checking state leads to resource busy errors and out-of-sync Terraform state files.

References:

• https://curl.se/windows/
• https://jqlang.org/download/
• https://pve.proxmox.com/wiki/Proxmox_VE_API#API_Tokens
• https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/qemu/{vmid}/status/current