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.
3.8 KiB
Language / Язык: English | Русский
Версии API (vSphere catalog majors 6–9)
Web UI и evidence/compatibility отчёты просматривают четыре целочисленных catalog majors, которые сопоставляются с label floors vSphere Automation API:
| Major | Метка vSphere | Строка версии contract |
|---|---|---|
| 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 |
Определения находятся в app/vsphere/contracts/matrix.py
(VERSIONS, PATH_FLOOR). Каждый зарегистрированный REST path имеет floor —
наименьший major, при котором он появляется в catalog — из того же
модуля. Undated paths по умолчанию получают наивысший major (9), пока не catalogued.
Runtime vs catalog
Это самое важное различие в проекте:
- Catalog major — управляет тем, что показывает Web UI endpoint tree,
/ui/api/catalog, и compatibility/evidence отчёты для данного major. - Runtime surface — симулятор всегда обслуживает полную зарегистрированную route table с deep handlers или DB-backed stubs, независимо от активного catalog major. Известный path никогда не возвращается как HTTP 501 из-за version floor.
Hot-swap catalog major — это documentation/browse
переключатель, а не compatibility gate для live traffic. См.
available_for_request() для точной
политики.
Cold start
GET /api/appliance/system/version сообщает version string текущего
выбранного runtime source (по умолчанию 8.0.2 / major 9, если процесс не
переопределяет app.state.runtime_source_version).
Hot-swap (catalog browse)
Просматривайте любой major в Web UI catalog или вызывайте:
POST /ui/api/contract/apply?major=7
Эффекты:
- Web UI catalog,
/ui/api/compatibilityи evidence отчёты переключаются на floor major 7 и ledger (evidence/vsphere-7.0.3.json). - Изменение process-local и не сохраняется; restart возвращает default (major 9).
- Зарегистрированные REST/SOAP routes продолжают отвечать своими реальными handlers независимо от применённого major.
Рекомендации для клиентов
- Большинству клиентов (pyvmomi, govmomi, Terraform, Pulumi, Ansible
uri) не нужно pin'ить catalog major — runtime surface не меняет форму на его основе. - Используйте catalog majors, когда нужно, чтобы Web UI / evidence view отражали более старую метку vSphere для документации или скриншотов.
- После apply перепроверьте
/ui/api/compatibility?major=Nдля активного catalog state.
Регенерация 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
См. Поверхность API и Совместимость.