Apache CloudStack 4.21 introduces the Extensions Framework, a lightweight and flexible mechanism that allows operators and developers to integrate external systems into CloudStack’s resource lifecycle management.

The Extensions Framework also ships with a built-in orchestrator for Proxmox VE, written entirely in Shell script. This script handles instance lifecycle operations such as Deploy, Start, Stop, Restart, Status, Destroy, and VM snapshots. Once created, the instance becomes part of CloudStack networking, with the Virtual Router (VR) managing services like Egress Rules, Port Forwarding, Load Balancing, and more, while CloudStack continues to handle the business logic for ACLs, limits, usage, events, and power-sync.

This approach is not the same as traditional hypervisor support in CloudStack (like KVM or VMware). In those cases, the hypervisor code lives deep within the CloudStack Java codebase, which is powerful yet complex, and often difficult for users to understand or modify. In contrast, the Proxmox extension is just a single Bash script: easy to read, easy to customise, and simple for users to extend with additional functionality if needed.

For more details on the Extensions Framework, read the blog here.

Preparing the Proxmox Environment

API Token

The Proxmox extensions communicate with the backend using the REST-like Proxmox VE API (https://pve.proxmox.com/wiki/Proxmox_VE_API). For this, an API Token needs to be created in Proxmox.

To add a new Token, in Proxmox VE UI, navigate to Datacenter -> Permissions -> API Tokens and click on the Add button. Note down the User, Token ID and the Secret Key.

If the Privilege Separation checkbox is ticked, the API token will not inherit the permissions from the User. In that case, the Api Token needs a separate permission to conduct VM lifecycle operations. To grant permissions to the API token, navigate to Datacenter -> Permissions and click on the Add button. Set path as /vms and the Role as PVEVMAdmin.

Networking

Apache CloudStack doesn’t deploy System VMs such as Virtual Routers (VR), Secondary Storage VMs (SSVM), or Console Proxy VMs (CPVM) on Proxmox VE. These components are provisioned only on supported native hypervisors (e.g., KVM, VMware, XCP-ng).

For User Instances running on Proxmox VE to communicate with the VR hosted on a native hypervisor, both the Proxmox VE Host and the native hypervisor Hosts must be connected to the same Layer 2 (L2) network segment.

On the Proxmox Host, a Linux bridge must be configured and attached to the L2 uplink interface. This bridge enables User Instances to access the full set of CloudStack network services through the existing VR.

To create a Linux Bridge in Proxmox VE, navigate to Datacenter -> Node -> System -> Network and click on Create Linux Bridge. Keep the VLAN aware checkbox un-checked.

Configuring Proxmox VE in CloudStack

Proxmox Extension in Apache CloudStack is of type Orchestrator, which means the extension resource will be tied to a Cluster in CloudStack.

The Proxmox extension must be registered with a Cluster, and then Hosts are added in CloudStack corresponding to each Proxmox VE Host. Templates or ISOs are also created in CloudStack and mapped to the corresponding Template or ISO on the Proxmox side.

Create a Cluster

To add a Proxmox VE Cluster in Apache CloudStack, in the CloudStack UI, navigate to Infrastructure -> Clusters, then click Add Cluster.

In the dialogue, select the appropriate Zone and Pod, define a Name, then set Hypervisor to External and Extension to Proxmox and then click OK.

Add a Host

To add a Proxmox VE Host, navigate to Infrastructure -> Hosts, then click Add Host.

In the dialogue, provide the required configuration details: url, user, token, secret, node and network_bridge.

If the Proxmox VE installation uses a self-signed TLS certificate, set verify_tls_certificate to false to skip certificate validation between the Apache CloudStack management server and Proxmox.

Create Template/ISO

In CloudStack, both ISOs and Templates from any Extension are represented as Templates.

To add a new Template, navigate to Images -> Templates, set Hypervisor to External, and Extension to Proxmox.

This Template will reference either an ISO or a Template on Proxmox VE, depending on how the external details are configured.

The URL field is mandatory but not used by the Extension. You can enter any value here to satisfy this requirement.

Fill in the other fields as you normally would when registering a Template in CloudStack, such as Zone, OS Type, and other options.

Then, set the external detail template_type to either Template or ISO:

• For ISOs: set iso_path to the corresponding file path in Proxmox.
• For Templates: set template_id to the VM ID in Proxmox that will be used as the Template.

Instance Operations in CloudStack

Deploying an Instance

To deploy an Instance, select the Template registered for Proxmox in the Add Instance form.

You can also specify a custom name to be displayed in Proxmox by adding an external detail with the key vm_name and the desired name as the value. This name will appear in Proxmox instead of the internal name generated by CloudStack.

Multiple Networks can be attached to the Instance during creation, and custom IP and MAC addresses can also be specified. Once the Instance is deployed, it will receive the IP and MAC address stored in CloudStack. The Instance will be connected to the Guest Network, with VR managing related network services.

Lifecycle Operations

Lifecycle operations supported out of the box are Start, Stop, Reboot and Destroy.

Custom Actions

In addition to the regular lifecycle operations, Custom Actions are also available, including CreateSnapshot, RestoreSnapshot, DeleteSnapshots, and ListSnapshot. These can be accessed by clicking the Run Action button.

Console Access

Console Access to Proxmox Instances from CloudStack via the Console Proxy is coming in CloudStack version 4.22.

Limitations

Instances created using Extensions are limited in functionality compared to traditional hypervisors. Some of these limitations for Proxmox are:
• Reconfiguring the NICs post-deployment is not possible.
• Other operations such as Migrate, Scale Instance, are not supported.
• SSH key injection and User Data services are not supported.
• Host capacity Metrics and Utilisation stats are not fetched in CloudStack.

Troubleshooting

For Troubleshooting tips, please check out the Extensions blog here.

Conclusion

The Proxmox Extension is a strong example of what the CloudStack Extension Framework enables. It’s intentionally lightweight, written in simple shell script, and easy to understand. At the same time, it provides a real value: full lifecycle management of Proxmox VE Instances directly from CloudStack, with a solid and reliable implementation.

Because the core logic is written in a shell script, extending the functionality doesn’t require navigating through thousands of lines of Java. Operators and developers can easily add new commands, adjust behaviours, or experiment with features tailored to their own environments.

While there are natural limits to its initial scope, the current feature set already addresses key requirements for managing Proxmox VE Instances in both testing and production scenarios.

In short, the Proxmox Extension shows that CloudStack’s Extension Framework is practical, powerful, and ready to help operators integrate new platforms into their CloudStack ecosystem without the complexity of traditional hypervisor integrations.