Files

T

Sergey Antropoff 777926487b Add a stateful Proxmox API console and broad handler coverage beyond the

initial QEMU slice, backed by imported contracts for majors 6–9.
- Implement durable handlers for access/auth, cluster, LXC, storage, HA,
  firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops
- Serve an interactive Web UI with catalog browsing, demo seed controls,
  and OpenAPI/help surfaces
- Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3
- Support in-memory runtime contract Apply (POST /ui/api/contract/apply)
  so /version and /api2 routes follow the selected major until restart
- Expand seed profiles (including demo-cluster), migrations 007–008, TLS
  gateway config, Compose/Makefile tooling, and compatibility evidence
- Tighten .gitignore for macOS, hidden directories (.*/), and local secrets

2026-07-16 01:08:01 +03:00

4.5 KiB

Raw Blame History

Getting started

Bring up a local laboratory cluster, authenticate, and exercise a first read/mutation cycle against the simulator.

Prerequisites

Docker and Docker Compose
make (optional but used by the documented commands)

Python, linters, and tests run inside containers. You do not need a local Python toolchain for day-to-day use.

Choose a path

Path	When to use
Published image	Fastest lab using `inecs/proxmox-api-simulator`
Helm / Kubernetes	Cluster install with Ingress + Let's Encrypt
Development checkout	Contribute / bind-mount source / HTTPS gateway on `:8007`

1a. Published image (Docker Hub)

Uses docker-compose.release.yml — PostgreSQL + runtime simulator from Hub. No source build required.

# from this repository, or download docker-compose.release.yml alone
docker compose -f docker-compose.release.yml pull
docker compose -f docker-compose.release.yml up -d
docker compose -f docker-compose.release.yml run --rm --entrypoint python \
  simulator -m app.simulation.seed_cli

Pin a version:

IMAGE_TAG=0.1.0 docker compose -f docker-compose.release.yml up -d

Make helpers (git checkout):

make release-up
make release-seed PROFILE=small

Host port	Service
`8006`	HTTP API + Web UI
`5432`	PostgreSQL (localhost only)

Migrations run automatically via the migrate one-shot service.

Then continue from Wait until ready.

1b. Development checkout

make install
make up

Services:

Host port	Service
`8006`	HTTP API + Web UI
`8007`	HTTPS nginx gateway → simulator
`5432`	PostgreSQL (localhost only)

Migrations apply automatically before the simulator becomes ready.

2. Wait until ready

curl http://localhost:8006/health/live
curl http://localhost:8006/health/ready

/health/ready returns HTTP 503 until PostgreSQL is reachable and the latest packaged migration is applied.

3. Seed a profile

make seed PROFILE=small

small creates node pve01, two QEMU guests (100, 101), one LXC (200), local storages, and the standard development principals. See Seed profiles for other sizes.

4. Check the API version

curl -s http://localhost:8006/api2/json/version | jq .

The cold-start contract defaults to the bundled PVE 9.2.3 snapshot in Docker Compose. Switch majors 6–9 from the Web UI or API versions.

5. Authenticate

curl -s -X POST \
  -d 'username=root@pam&password=secret' \
  http://localhost:8006/api2/json/access/ticket | jq .

Save ticket and CSRFPreventionToken from data. For mutations, send:

Cookie: PVEAuthCookie=<ticket>
Header: CSRFPreventionToken: <token>

Details: Authentication.

6. List guests and start one

# replace TICKET / CSRF from the previous response
curl -s -H "Cookie: PVEAuthCookie=$TICKET" \
  http://localhost:8006/api2/json/nodes/pve01/qemu | jq .

curl -s -X POST \
  -H "Cookie: PVEAuthCookie=$TICKET" \
  -H "CSRFPreventionToken: $CSRF" \
  http://localhost:8006/api2/json/nodes/pve01/qemu/100/status/start | jq .

Async operations return a UPID string. Poll until the task finishes:

curl -s -H "Cookie: PVEAuthCookie=$TICKET" \
  "http://localhost:8006/api2/json/nodes/pve01/tasks/${UPID}/status" | jq .

7. Open the Web UI

Visit http://localhost:8006/ for the interactive console, contract catalog (PVE 6–9), compatibility view, runtime contract apply, and demo-cluster controls. See Web UI for light/dark theme screenshots and the full feature list.

8. Try a client library

# from the repository root after make up + seed
python examples/python/proxmoxer_cookbook.py

More stacks: Clients and examples/.

You’re done when…

/health/ready returns {"status":"ok"} (or equivalent OK body)
/api2/json/version reports the active contract version
Ticket login succeeds for root@pam
nodes/pve01/qemu lists seeded VMs
At least one power or create path returns a UPID that completes successfully

Next steps

Configuration — env vars, workers, contract path
API versions — hot-swap majors 6–9
Clients — Ansible, Terraform, Pulumi, Go, Java, Perl
Operations — reseed, migrate, upgrades

4.5 KiB Raw Blame History Unescape Escape