Skip to content

fakepve

A lightweight fake of the Proxmox VE API, for testing code that drives Proxmox without needing a cluster, and for putting that code through the things a real cluster does to it: slow shutdowns, locked VMs, lost quorum, flaky networks, Ceph trouble.

It is for people writing Ansible modules, Terraform providers, proxmoxer scripts, and Go, Python or JavaScript clients for Proxmox, and for anyone who wants their tests and pipelines to run without a PVE host. It is one Python process on aiohttp: no PVE, QEMU, Ceph or corosync.

Test tool: bind it to loopback. fakepve has no real security. Its default login, root@pam / secret, is public, so anyone who can reach the port can do anything to the fake. Run it on a loopback address (the default), publish container ports as 127.0.0.1:8006:8006, and set PVE_PASS when anyone but you can reach the port. See the security policy.

Thirty seconds

pip install 'fakepve[crypto]'
fakepve examples/guests.json --time-scale 0
fakepve listening on https://127.0.0.2:8006

Starting the fake and logging in

Log in as root@pam with password secret. Getting started goes on from here.

What it does

  • Logins as PVE has them: tickets with CSRF tokens and expiry, API tokens, optional per-path permissions, two-factor logins (the NeedTFA answer).
  • Every endpoint of the PVE 9 API schema answers: 680 methods on 449 paths, validated with PVE's wording, under /api2/json and /api2/extjs. See the endpoint reference.
  • Stateful where a client reads back what it did: VM power, config and pending changes, tasks with real UPIDs, storage config and content, pools, the firewall, guest agent, consoles.
  • Real errors, by name: 2314 errors PVE can return, each raised with pve.fail(..., error='name'). See Errors.
  • Faults on demand: slow guests, locks, migrations, HA, lost quorum, offline nodes, flaky networks, Ceph, full storage, expired tickets, 403s. See Scenarios.
  • Easy to run in CI: a command line, a pytest-friendly class, a Dockerfile, and recipes for GitHub, Forgejo and Gitea, and GitLab. See CI.

It is a fake, not a copy of PVE; the known gaps are stated plainly.

Support

fakepve is free and always will be. If it saves you time, you can buy me a coffee.

Buy me a coffee at ko-fi.com

Licence

Licensed under the GNU Affero General Public License, version 3 or later. The data in src/fakepve/data/ is derived from Proxmox VE (also AGPL-3.0). Not affiliated with or endorsed by Proxmox Server Solutions GmbH; Proxmox is a registered trademark of Proxmox Server Solutions GmbH.