inecs
f8d3cbdd59
Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API contracts, docs, client examples, and the unit/integration/compatibility test suite for local client and tooling labs without a real vCenter.
2.9 KiB
Language / Язык: English | Русский
API versions (vSphere catalog majors 6–9)
The Web UI and evidence/compatibility reports browse four integer catalog majors that map onto vSphere Automation API label floors:
| Major | vSphere label | Contract version string |
|---|---|---|
| 6 | 7.0 | 7.0.0 |
| 7 | 7.0 U3 | 7.0.3 |
| 8 | 8.0 | 8.0.0 |
| 9 | 8.0 U2 (Automation 9.1 surface) | 8.0.2 |
Definitions live in app/vsphere/contracts/matrix.py
(VERSIONS, PATH_FLOOR). Each registered REST path has a floor — the
lowest major at which it appears in the catalog — sourced from the same
module. Undated paths default to the highest major (9) until catalogued.
Runtime vs catalog
This is the most important distinction in the project:
- Catalog major — controls what the Web UI endpoint tree,
/ui/api/catalog, and compatibility/evidence reports show for a given major. - Runtime surface — the simulator always serves the full registered route table with deep handlers or DB-backed stubs, independent of the active catalog major. A known path is never returned as HTTP 501 because of a version floor.
Hot-swapping the catalog major is therefore a documentation/browse
switch, not a compatibility gate on live traffic. See
available_for_request() for the exact
policy.
Cold start
GET /api/appliance/system/version reports the version string of the
currently selected runtime source (defaults to 8.0.2 / major 9 unless the
process overrides app.state.runtime_source_version).
Hot-swap (catalog browse)
Browse any major in the Web UI catalog, or call:
POST /ui/api/contract/apply?major=7
Effects:
- The Web UI catalog,
/ui/api/compatibility, and evidence reports switch to major 7's floor and ledger (evidence/vsphere-7.0.3.json). - The change is process-local and not persisted; a restart returns to the default (major 9).
- REST/SOAP routes already registered continue to answer with their real handlers regardless of the applied major.
Client guidance
- Most clients (pyvmomi, govmomi, Terraform, Pulumi, Ansible
uri) do not need to pin a catalog major — the runtime surface does not change shape based on it. - Use catalog majors when you specifically want the Web UI / evidence view to reflect an older vSphere label for documentation or screenshots.
- After apply, re-check
/ui/api/compatibility?major=Nfor the active catalog state.
Regenerating catalog artifacts
make vsphere-bundles # stub OpenAPI matrices + evidence ledgers
make vsphere-universe # regenerate universe.json from the Broadcom operations index
make evidence # regenerate per-major verified surface evidence ledgers
See API surface and Compatibility.