Files

T

Sergey Antropoff 48df10b17e Prepare 0.1.0 for lab release: durable handlers, HTTP Compose, CI, and pulumi-tests.

- Harden DB-backed handlers and seed profiles; align client wire shapes for
  cluster resources, QEMU config, and node SSL fields
- Serve plain HTTP on Compose :8006; keep TLS optional (--profile tls) and
  terminate HTTPS at Kubernetes Ingress
- Add pulumi-tests (full contract surface majors 6–9 + BPG lifecycle) and
  make pulumi-tests
- Ship bilingual docs, CHANGELOG, SECURITY, CONTRIBUTING, and GitHub Actions
  (make ci + Compose/Helm validation)

2026-07-18 04:18:05 +03:00

5.2 KiB

Raw 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 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

5.2 KiB Raw Blame History Unescape Escape