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.
78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
**Language / Язык:** [English](../api-versions.md) | [Русский](api-versions.md)
|
||
|
||
# Версии 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`](../../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()`](../../app/vsphere/contracts/matrix.py) для точной
|
||
политики.
|
||
|
||
## 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 или вызывайте:
|
||
|
||
```http
|
||
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
|
||
|
||
```bash
|
||
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](api-surface.md) и [Совместимость](compatibility.md).
|