Automating VPS Management via Proxmox and Virtualizor API

Automating VPS Management and Provisioning via API (Proxmox/Virtualizor): Building a Professional Internal Admin System

In the era of Infrastructure as Code (IaC), performing manual operations on the Graphical User Interface (GUI) of virtualization platforms like Proxmox or Virtualizor is no longer suitable for businesses that demand speed and precision. Automating the VPS provisioning process helps minimize human error and optimizes deployment time from hours to mere seconds. This article will guide you on how to communicate with the APIs of the two most popular virtualization platforms today to build a complete internal VPS management system.

1. Why Use API Communication Instead of GUI?

While a GUI is excellent for individual configurations, when you need to manage hundreds or thousands of VPS instances, the API becomes an irreplaceable tool for the following reasons:

Scalability: Automate the creation of bulk VPS instances based on real-time system demand.
Integration: Connect directly to Billing systems, Monitoring tools, or Client Portals.
Consistency: Ensure every VPS created adheres to configuration standards for RAM, CPU, Disk, and Network without discrepancy.
Audit and Logging: Every operation performed via API can be logged in detail within an internal database for auditing purposes.

2. Communicating with Proxmox VE API

Proxmox VE provides a powerful RESTful API. Every operation—from managing Storage and Networking to controlling Virtual Machines (VM) and Containers (LXC)—can be performed through specific Endpoints.

Authentication Mechanism

Proxmox uses a Ticket mechanism or API Tokens. API Tokens are highly recommended for automation applications due to their security and ease of managing Access Control Lists (ACL).


// Defining the Authentication Header structure for Proxmox API
interface ProxmoxAuth {
    node: string;
    tokenName: string;
    tokenValue: string;
}

function getProxmoxHeaders(auth: ProxmoxAuth): Record {
    return {
        "Authorization": `PVEAPIToken=${auth.tokenName}=${auth.tokenValue}`,
        "Content-Type": "application/json",
        "Accept": "application/json"
    };
}

const myAuth: ProxmoxAuth = {
    node: "pve-node-01",
    tokenName: "root@pam!automation",
    tokenValue: "xxxx-xxxx-xxxx-xxxx"
};

console.log("Headers ready for Proxmox API calls.");

Automated VPS Creation (Clone from Template)

The most efficient way to provision a VPS quickly is to use the Clone feature from a pre-configured Virtual Machine Template that already includes the OS and basic software.


// Interface for VPS creation request data
interface CloneVMRequest {
    newid: number;
    name: string;
    targetNode: string;
    fullClone: boolean; // true for total separation from template
}

async function cloneProxmoxVM(templateId: number, data: CloneVMRequest): Promise {
    const url = `https://pve-api.example.com:8006/api2/json/nodes/${data.targetNode}/qemu/${templateId}/clone`;
    
    console.log(`Sending Clone request for VM ${templateId} to new ID ${data.newid}...`);
    // Actual fetch() logic would be implemented here
    console.log(`VM ${data.name} is being initialized in the background.`);
}

cloneProxmoxVM(100, { newid: 101, name: "web-server-01", targetNode: "node-1", fullClone: true });

3. Communicating with Virtualizor API

Virtualizor is a popular Control Panel for VPS Hosting providers. Its API focuses heavily on resource management and bandwidth limitations.

API Call Structure

Unlike Proxmox, Virtualizor typically receives parameters via GET or POST methods accompanied by an API Key and API Pass.


// Logic for building Virtualizor API URLs
interface VirtualizorConfig {
    apiKey: string;
    apiPass: string;
    baseUrl: string;
}

function buildVirtualizorUrl(config: VirtualizorConfig, action: string, params: Record): string {
    const query = new URLSearchParams({
        api: "json",
        apikey: config.apiKey,
        apipass: config.apiPass,
        act: action,
        ...params
    });
    return `${config.baseUrl}?${query.toString()}`;
}

const vConfig: VirtualizorConfig = {
    apiKey: "VZR_KEY_123",
    apiPass: "VZR_PASS_456",
    baseUrl: "https://vps-master.example.com:4085/index.php"
};

console.log(buildVirtualizorUrl(vConfig, "vpsmanage", { vpsid: "123", status: "reboot" }));

4. Core Control Operations: Reboot, Stop, Delete

To build an internal dashboard, you need to implement three basic power state functions. Each platform handles Tasks differently (Proxmox returns a Task ID for tracking, while Virtualizor usually returns the status directly).

Operation	Proxmox Endpoint (QEMU)	Virtualizor Action
Start	POST /nodes/{node}/qemu/{vmid}/status/start	act=start
Reboot	POST /nodes/{node}/qemu/{vmid}/status/reboot	act=reboot
Delete (Terminate)	DELETE /nodes/{node}/qemu/{vmid}	act=terminate


// Multi-platform VM power state control (Abstraction Layer)
type PowerAction = "start" | "stop" | "reboot";

async function setPowerState(platform: "Proxmox" | "Virtualizor", vpsId: string, action: PowerAction) {
    console.log(`[${platform}] Executing ${action} command for VPS ID: ${vpsId}`);
    
    if (platform === "Proxmox") {
        // Call Proxmox API status/{action}
    } else {
        // Call Virtualizor API act={action}
    }
    
    return { success: true, message: `Command ${action} has been sent.` };
}

setPowerState("Virtualizor", "vps_007", "reboot").then(res => console.log(res.message));

5. Building an Internal Admin System: Architecture and Data Flow

When building a custom VPS management dashboard, you should never call the API directly from the user's browser (Client-side) for security reasons (to avoid exposing API Keys). Instead, build a Middleware/Backend to act as an intermediary.

Workflow for a New Provisioning Request:

Authentication: Verify the employee/user permissions within the internal system.
Resource Check: Call the API to see which physical Node has enough RAM/Disk to host the new VM.
API Execution: Send the Clone/Create command to the virtualization platform.
Network Configuration: Automatically assign an IP and configure Cloud-init (if using Proxmox) to set a default SSH password.
Storage: Save the VM ID and customer information into the internal Database (MySQL/PostgreSQL).


// Structure of an internal VPS record in the Database
interface InternalVPSRecord {
    id: string; // Internal system UUID
    remoteId: number; // VMID on Proxmox/Virtualizor
    ownerId: string;
    ipv4: string;
    specs: {
        cpu: number;
        ram: number;
    };
    platform: "Proxmox" | "Virtualizor";
}

const newRecord: InternalVPSRecord = {
    id: "vps-local-999",
    remoteId: 5022,
    ownerId: "user_thaovien_01",
    ipv4: "103.1.2.3",
    specs: { cpu: 2, ram: 4096 },
    platform: "Proxmox"
};

console.log("VPS data synchronized to internal Database.");

6. Error Handling and Queue Mechanisms

VPS creation can take several minutes. You should not keep the HTTP request waiting too long. Use a task queue such as BullMQ or RabbitMQ.

Retry Logic: If the Proxmox API times out, the system will automatically retry after 30 seconds.
Webhooks: Register to receive notifications from Virtualizor when a task is completed to update the status on the Dashboard.

7. Conclusion: The Importance of Mastering APIs

Mastering the APIs of virtualization platforms like Proxmox or Virtualizor opens the door to building unique, flexible Cloud service systems like a mini-AWS or DigitalOcean. By combining TypeScript, Node.js, and virtualization platforms, you not only optimize internal operations but also create significant technical value for your business.

Start by writing simple scripts to Reboot a VPS, then gradually develop a full automated provisioning system. Good luck building your own "Cloud"!

Automating VPS Management and Allocation via API (Proxmox/Virtualizor)