Sergey Antropoff
48df10b17e
- 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)
80 lines
2.7 KiB
Markdown
80 lines
2.7 KiB
Markdown
**Language / Язык:** [English](api-versions.md) | [Русский](ru/api-versions.md)
|
||
|
||
# API versions (PVE 6–9)
|
||
|
||
The simulator ships authoritative imported contracts for four Proxmox VE majors.
|
||
Handler registry coverage is **100% verified** for each:
|
||
|
||
| Major | Source version | Declared methods | Handler coverage |
|
||
|---|---|---:|---:|
|
||
| 6 | 6.4-15 | 504 | 100% |
|
||
| 7 | 7.4-16 | 540 | 100% |
|
||
| 8 | 8.4.5 | 605 | 100% |
|
||
| 9 | 9.2.3 | 675 | 100% |
|
||
|
||
Older majors reuse the current semantic handlers plus path synonyms registered
|
||
in `app/handlers/legacy_aliases.py` (for example historical Ceph and backup path
|
||
spellings).
|
||
|
||
## Cold start
|
||
|
||
Set `CONTRACT_SNAPSHOT` to a normalized snapshot path. Docker Compose pins the
|
||
bundled PVE **9.2.3** revision by default.
|
||
|
||
`GET /api2/json/version` reports fields derived from the **active** snapshot’s
|
||
`source_version`.
|
||
|
||
## Hot-swap (runtime)
|
||
|
||
Browse any major in the Web UI catalog, then **Apply as runtime**, or call:
|
||
|
||
```http
|
||
POST /ui/api/contract/apply?major=7
|
||
```
|
||
|
||
Effects:
|
||
|
||
- In-memory `/api2/json` and `/api2/extjs` routes are replaced under an
|
||
application lock.
|
||
- `/version`, OpenAPI, implementation metadata, and compatibility state refresh
|
||
for the new major.
|
||
- The change is **process-local** and **not persisted**.
|
||
- Restart restores `CONTRACT_SNAPSHOT`.
|
||
|
||
Catalog browse (`GET /ui/api/catalog?major=N`) does **not** by itself change the
|
||
runtime; only apply does.
|
||
|
||
### Client guidance
|
||
|
||
- Pin the major explicitly in CI (cold-start env **or** apply + assert
|
||
`/version` before the suite).
|
||
- Mid-flight hot-swap can invalidate in-progress client assumptions about
|
||
schemas and paths — avoid during long Terraform/Ansible runs unless the run
|
||
owns the switch.
|
||
- After apply, re-check `/admin/compatibility` for the active runtime.
|
||
|
||
## Fallback modes
|
||
|
||
`CONTRACT_FALLBACK` controls undeclared-handler behaviour:
|
||
|
||
| Value | Behaviour |
|
||
|---|---|
|
||
| `error` (default) | HTTP 501 with an explicit pending-handler style message |
|
||
| `schema-default` | Synthesize a return value from the contract schema |
|
||
| `fixture` | Return only fixture data embedded in the method contract |
|
||
|
||
With full handler coverage on the active contract, declared methods should not
|
||
hit the fallback. Keep `error` so regressions remain visible.
|
||
|
||
## Evidence vs registry
|
||
|
||
**Registry coverage** means every declared method has a registered semantic
|
||
handler (no systematic 501 for that contract).
|
||
|
||
**Verified** in this project’s sense means the majors are exercised through the
|
||
compatibility and automated suites for handler presence across 6–9. Multi-
|
||
dimension evidence JSON can still expand over time for deeper edge-case claims;
|
||
prefer live `/admin/compatibility` when the process is running.
|
||
|
||
See [Compatibility](compatibility.md).
|