CloudStack Proxmox VE Extension

An Apache CloudStack Orchestrator extension that manages virtual machines on Proxmox VE.

CloudStack invokes the extension as a command line program, passing an action and the path to a JSON payload; the extension talks to the Proxmox API and writes a single JSON document to stdout. Everything is implemented on top of the Python standard library, so the extension has no runtime dependencies and runs with the management server's system interpreter.

Installation

pip install cloudstack-extension-proxmox-ngine

This provides the cloudstack-extension-proxmox command. CloudStack expects to find an executable inside the extension directory, so link the command into place:

mkdir -p /usr/share/cloudstack-management/extensions/Proxmox-Ngine
ln -s "$(command -v cloudstack-extension-proxmox)" \
      /usr/share/cloudstack-management/extensions/Proxmox-Ngine/proxmox.sh

Register the extension in CloudStack (Extensions → Add Extension, type Orchestrator) and add the Proxmox connection details as extension or host details.

Usage

cloudstack-extension-proxmox <action> <payload.json> [timeout-seconds]

stop and delete are idempotent: a VM that no longer exists is reported as success.

Payload

The payload is written by CloudStack. The fields the extension reads are:

As a library

from cloudstack_extension_proxmox_ngine import ProxmoxManager

manager = ProxmoxManager.from_config_file("payload.json")
print(manager.status())
# {'status': 'success', 'power_state': 'poweron'}

Operations return the CloudStack result document and raise ProxmoxError on failure.

Development

The project uses uv:

uv sync --group dev
uv run pytest              # tests with coverage
uv run black --check .     # formatting
uv run ruff check .        # linting
uv run mypy                # type checking

Pull requests run the same checks on Python 3.10 through 3.14.

License

Apache License 2.0 — see LICENSE.