Files

T

Sergey Antropoff 0773f721ea Align sized cluster seeds and GET dumps with PVE wire shapes; restyle DATA panel.

- Scale small/large/big seeds (3×50 / 10×1000 / 20×2000) with proportional
  backups, snapshots, HA, replication, Ceph capacity, and OSD totals
  (10 / 100 / 500) plus matching node disks and crush/pg metadata
- Enrich handler responses for apt, certificates, qemu/lxc status, storage,
  SDN, metrics export, and related cluster/node dumps
- Flatten nested body_example fields into PARAMS and sync the request body
  via dotted paths (oVirt-style)
- Restyle DATA controls as size cards with full-width Reset to minimal /
  Refresh stats; unload reloads the minimal cluster

2026-07-18 08:46:11 +03:00

5.2 KiB

Raw Permalink Blame History

Language / Язык: English | Русский

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 / HTTP API on `:8006`

1a. Published image (Docker Hub)

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

Laboratory / CI only — rotate TICKET_SIGNING_KEY and the DB password before any shared or networked demo. See SECURITY.md.

# from this repository (compose file + docker/tls/)
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 (same port as real PVE; real PVE uses HTTPS)
`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 (same port as real PVE; real PVE uses HTTPS)
`5432`	PostgreSQL (localhost only)

On real Proxmox VE the REST API is only https://<host>:8006/api2/json/.... The lab publishes plain HTTP on host :8006; see Ports and TLS. Optional HTTPS for proxmoxer: docker compose --profile tls → https://localhost:8443/. Host :8007 is not used (on hardware it is typically PBS, not PVE API).

Migrations apply automatically before the simulator becomes ready.

2. Wait until ready

curl -sS http://localhost:8006/health/live
curl -sS 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 -sS 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 -sS -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 -sS -H "Cookie: PVEAuthCookie=$TICKET" \
  http://localhost:8006/api2/json/nodes/pve01/qemu | jq .

curl -sS -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 -sS -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 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

5.2 KiB Raw Permalink Blame History Unescape Escape