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
This commit is contained in:
Sergey Antropoff
+79
-31
@@ -1,16 +1,25 @@
|
||||
# Compatibility report — 0.1.0
|
||||
|
||||
This report records evidence for simulator release 0.1.0 against the bundled
|
||||
Proxmox VE 9.2.3 API contract. It is a limitation matrix, not a claim of general
|
||||
Proxmox compatibility.
|
||||
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.
|
||||
|
||||
## Summary
|
||||
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% | Imported immutable API Viewer artifact |
|
||||
| Stateful semantics implemented on current main | 39 | 5.78% | Handler registry and unit/integration tests |
|
||||
| Schema-only or explicitly unsupported | 636 | 94.22% | Default 501 fallback |
|
||||
| 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`,
|
||||
@@ -19,37 +28,76 @@ 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.
|
||||
|
||||
## Implemented surface
|
||||
## Coverage by Proxmox major
|
||||
|
||||
- Core: version, ticket login, node list/status, and cluster resources.
|
||||
- QEMU: list, configuration, current status, start, and stop.
|
||||
- Tasks: node task list, status, and append-only log.
|
||||
- Authentication: ticket cookie and ticket-bound CSRF validation for mutations,
|
||||
plus hashed API-token authentication without CSRF and token privilege
|
||||
separation at the contract-derived ACL boundary.
|
||||
- Persistence: PostgreSQL resources, durable leased tasks, and deterministic
|
||||
`small` seed data.
|
||||
| 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 | 0.1.0 behavior |
|
||||
| Area | Current behavior |
|
||||
|---|---|
|
||||
| Other imported endpoints | Registered, but return explicit unsupported errors |
|
||||
| API tokens and broad ACL administration | Primitives exist; public management surface is incomplete |
|
||||
| QEMU lifecycle | No create, update, delete, snapshots, clone, or migration |
|
||||
| LXC, storage, pools, backup, HA | Contract-only; no stateful semantics yet |
|
||||
| Observation parity | Responses are contract-tested, but no sanitized real-PVE observation corpus exists |
|
||||
| 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 only; Terraform and other clients are not certified |
|
||||
| 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 |
|
||||
|
||||
The live `/admin/compatibility` endpoint is the machine-readable source for
|
||||
declared and implemented counts. Unsupported methods remain failures by default
|
||||
so the simulator cannot silently overstate compatibility.
|
||||
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. Evidence is loaded from the immutable
|
||||
`evidence/pve-9.2.3-0.1.0.json` manifest, where every method/dimension claim cites
|
||||
the tests that support it. Dynamic route registration itself proves only the
|
||||
route/method dimension; it does not imply semantic compatibility. Markdown and
|
||||
HTML renderings are available at `/admin/compatibility.md` and
|
||||
`/admin/compatibility.html`.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user