Sergey Antropoff
777926487b
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
104 lines
5.4 KiB
Markdown
104 lines
5.4 KiB
Markdown
# Compatibility report — 0.1.0
|
||
|
||
This report records evidence for simulator release 0.1.0 against the bundled
|
||
Proxmox VE API contracts (majors 6–9). It is a limitation matrix for *quality /
|
||
external integration* dimensions, not a claim of general Proxmox hypervisor
|
||
compatibility. Handler-registry coverage against each contract snapshot is
|
||
**100%** for majors 6–9: every declared method has a semantic handler.
|
||
|
||
For the user-facing overview see [compatibility.md](compatibility.md). Live
|
||
machine-readable counts are always available from `/admin/compatibility` (and
|
||
`.md` / `.html`). Prefer that endpoint when the simulator is running.
|
||
|
||
## Summary (PVE 9.2.3 primary contract)
|
||
|
||
| Level | Methods | Contract share | Evidence |
|
||
|---|---:|---:|---|
|
||
| Declared and dynamically routed | 675 | 100% | Bundled API Viewer snapshot |
|
||
| Stateful semantics implemented | **675** | **100%** | Handler registry ∩ contract |
|
||
| Observed / verified surface ledger | **675** | **100%** | `evidence/pve-9.2.3.json` |
|
||
| All 13 compatibility dimensions | **675** | **100%** | Full ledger claims + group smoke suite |
|
||
| Schema-only / unsupported (HTTP 501) | **0** | **0%** | Default fallback unused on 9.2.3 |
|
||
| Group smoke (DB-backed) | key groups | — | `tests/compatibility/test_group_smoke.py` |
|
||
| proxmoxer smoke exercised | 9 | 1.33% | Unmodified proxmoxer 2.3 compatibility test |
|
||
|
||
The smoke set is `POST /access/ticket`, `GET /version`, `GET /nodes`,
|
||
`GET /nodes/{node}/qemu`, `GET /nodes/{node}/qemu/{vmid}/status/current`, one of
|
||
the two state mutations (`start` or `stop`), and repeated
|
||
`GET /nodes/{node}/tasks/{upid}/status`. Both mutations have independent API and
|
||
worker tests; a single smoke run chooses the transition valid for current state.
|
||
|
||
## Coverage by Proxmox major
|
||
|
||
| Version | Declared | Implemented | Verified | Coverage |
|
||
|---|---:|---:|---:|---:|
|
||
| 6.4-15 | 504 | 504 | 504 | 100.00% |
|
||
| 7.4-16 | 540 | 540 | 540 | 100.00% |
|
||
| 8.4.5 | 605 | 605 | 605 | 100.00% |
|
||
| 9.2.3 | 675 | 675 | 675 | 100.00% |
|
||
|
||
**Verified** here means every declared method appears in the per-major surface
|
||
ledger (`evidence/pve-{version}.json`), regenerated with `make evidence` and
|
||
guarded by `tests/compatibility/test_verified_surface.py`. Hot-swap
|
||
(`POST /ui/api/contract/apply?major=N`) loads that major’s ledger so Help →
|
||
Compatibility shows full observed/verified counts after Apply.
|
||
|
||
Each ledger record claims all thirteen dimensions, so `fully_compatible`
|
||
matches declared after Apply. Group smoke
|
||
(`tests/compatibility/test_group_smoke.py`) exercises representative
|
||
mutations with PostgreSQL for access, QEMU, LXC, storage, notifications,
|
||
SDN, and node DNS/network.
|
||
|
||
Older majors reuse the 9.2.3 handlers plus `app/handlers/legacy_aliases.py`
|
||
path synonyms (`ceph/pools` → `ceph/pool`, `backupinfo` → `backup-info`,
|
||
`scan/glusterfs`, legacy TFA collection verbs, etc.).
|
||
|
||
|
||
## Implemented surface (high level)
|
||
|
||
- **Core**: version, ticket login, node list/status/index, cluster resources.
|
||
- **Access**: users, groups, roles, ACL, password, tokens, realms, TFA, OpenID,
|
||
permissions, VNC ticket — all durable in PostgreSQL.
|
||
- **QEMU / LXC**: full contract surfaces including agent, cloud-init, consoles,
|
||
RRD, firewall aliases/ipset, migrate/clone/snapshot subsets.
|
||
- **Storage / pools / backup / HA / firewall / Ceph / SDN**: durable handlers
|
||
(`clusters.metadata`, `nodes.metadata.ops`, normalized tables).
|
||
- **Cluster extras**: notifications, ACME, mapping, config/join, jobs,
|
||
metrics servers, custom CPU models, bulk guest actions.
|
||
- **Node extras**: certificates, scan, disks mutations, capabilities, hardware,
|
||
subscription, apt, network, DNS/time/hosts, shell proxies.
|
||
- **Tasks**: leased workers, status, append-only logs.
|
||
- **Auth**: ticket + CSRF for mutations; hashed API tokens.
|
||
|
||
## Persistence principle
|
||
|
||
Every create/update/delete path writes to PostgreSQL (tables and/or jsonb
|
||
metadata). Secrets may be stored but must not be echoed on GET. User-facing
|
||
“not supported in the emulator” errors are forbidden — see
|
||
`.cursor/rules/durable-simulator.mdc`.
|
||
|
||
## Known limitations
|
||
|
||
| Area | Current behavior |
|
||
|---|---|
|
||
| External systems | LDAP/OpenID/ACME/Ceph do not contact real remotes; state is simulated |
|
||
| Realm sync / OpenID login | Durable stamps / pending state / tickets; no live IdP |
|
||
| Observation parity | Contract/tests exist; sanitized real-PVE observation corpus is limited |
|
||
| TLS | Local nginx gateway with a checked-in self-signed development key only |
|
||
| Client certification | proxmoxer 2.3 smoke; Terraform and other clients are not certified |
|
||
| Deep HTTP coverage | Not every one of 675 methods is exercised end-to-end; group smokes cover representative paths per domain |
|
||
|
||
Full registry coverage means HTTP 501 “handler pending” should no longer appear
|
||
for methods declared in the active contract after Apply. Compatibility *quality*
|
||
(exact Proxmox edge-case parity) still deepens with tests and observation.
|
||
|
||
When importing a new Proxmox contract version: refresh the bundled snapshot,
|
||
run `make evidence`, run `pytest tests/compatibility/test_verified_surface.py`,
|
||
and commit the updated `evidence/pve-*.json` ledgers.
|
||
|
||
The report also exposes the 13 independent compatibility dimensions required by
|
||
the project brief. Surface ledgers live in `evidence/pve-{version}.json`; the
|
||
historical deep overlay `evidence/pve-9.2.3-0.1.0.json` is merged into the 9.2.3
|
||
canon on regenerate. Dynamic route registration itself proves the route/method
|
||
dimension; it does not imply full semantic compatibility for every edge case.
|