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.
168 lines
11 KiB
Markdown
168 lines
11 KiB
Markdown
**Language / Язык:** [English](../api-coverage.md) | [Русский](api-coverage.md)
|
||
|
||
# Матрица покрытия vSphere API
|
||
|
||
Реестр, ориентированный на автоматизацию: [`app/vsphere/rest/coverage.py`](../../app/vsphere/rest/coverage.py).
|
||
Стабы universe от Broadcom: [`app/vsphere/rest/universe.json`](../../app/vsphere/rest/universe.json) (из публичного индекса операций).
|
||
Уровни по мажорам + бандлы стаб-OpenAPI: [`app/vsphere/contracts/matrix.py`](../../app/vsphere/contracts/matrix.py) → `contracts/vsphere/<version>/manifest.json`.
|
||
|
||
## Broadcom в сравнении с этим симулятором
|
||
|
||
Публичный источник (собран скрапингом): [Индекс операций vSphere Automation API (9.1 Latest)](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/operation-index/)
|
||
|
||
| Поверхность | Количество | Примечания |
|
||
|---|---:|---|
|
||
| Индекс операций Broadcom | **1348** | GET 628 / POST 422 / DELETE 114 / PUT 93 / PATCH 91 |
|
||
| Сгенерированные уникальные маршруты `verb + path` | **~1037** | Один и тот же HTTP-путь может обслуживать несколько именованных операций (`?action=…`, `$Task`) |
|
||
| Реестр симулятора (core + стабы + `/rest`) | **1077** | Глубокие core-обработчики перезаписывают записи стабов на том же пути |
|
||
| Глубокие core-обработчики | **104** | Поведение seeded-инвентаря / жизненного цикла / authz |
|
||
| Строки поверхности, поддерживаемые БД (`vsphere_api_state`) | **~540+** | Загружаются seed для каждого GET-маршрута `/api` + лабораторные дополнения |
|
||
|
||
Регенерируйте universe после обновления дампа индекса:
|
||
|
||
```bash
|
||
python scripts/generate_vsphere_universe.py
|
||
make vsphere-bundles
|
||
```
|
||
|
||
Обновление живой статистики / регенерация артефактов:
|
||
|
||
```bash
|
||
curl -sk https://localhost/ui/api/compatibility?major=9
|
||
make vsphere-surface
|
||
python scripts/write_vsphere_bundles.py
|
||
python scripts/write_vsphere_evidence.py
|
||
```
|
||
|
||
| Мажор | Метка | Реализовано / universe | Покрытие | Примечания |
|
||
|---|---|---:|---:|---|
|
||
| 6 | vSphere 7.0 | 31 / 1077 | 2.9% | Только floor каталога/evidence |
|
||
| 7 | vSphere 7.0 U3 | 77 / 1077 | 7.2% | Только floor каталога/evidence |
|
||
| 8 | vSphere 8.0 | 103 / 1077 | 9.6% | Только floor каталога/evidence |
|
||
| 9 | vSphere 8.0 U2 / поверхность Automation 9.1 | **1077 / 1077** | **100%** | Глубокие обработчики + DB-backed поверхность Broadcom |
|
||
|
||
Числа берутся из `GET /ui/api/compatibility?major=N` и
|
||
`evidence/vsphere-*.json` (`make vsphere-bundles`).
|
||
|
||
Hot-swap (`POST /ui/api/contract/apply?major=N`) меняет **catalog** major для
|
||
Web UI / evidence-отчётов. **Runtime всегда обслуживает полную
|
||
зарегистрированную поверхность** — известные пути не получают HTTP 501 из-за
|
||
version floor.
|
||
|
||
## Плоскости
|
||
|
||
| Плоскость | По умолчанию | Примечания |
|
||
|---|---|---|
|
||
| Native REST `/api`, `/rest` | включена | Основная лабораторная поверхность |
|
||
| Native SOAP `/sdk` | включена | Подмножество PropertyCollector + задачи ВМ |
|
||
| Стаб Proxmox `/api2/*` | **выключена** (`ENABLE_PVE_STUB=false`) | Опциональный legacy |
|
||
|
||
## Auth и синтетические данные
|
||
|
||
| Пункт | Детали |
|
||
|---|---|
|
||
| Пользователи | `administrator`, `readonly`, `operator`, `vmadmin` `@vsphere.local` / `VMware1!` |
|
||
| AuthZ | Проверка привилегий по роли на мутирующих эндпоинтах (403 `unauthorized`) |
|
||
| Seed `large` | 10 хостов, **1000 ВМ**, 4 datastore, DVS, папки, права |
|
||
| Seed `demo-cluster` | 20 хостов, 1000 ВМ (загрузка demo в UI) |
|
||
| Seed `small` | 3 хоста, 5 именованных ВМ (тесты) |
|
||
|
||
## Домены REST
|
||
|
||
### Глубокие (core) на мажоре 9
|
||
|
||
- Сессия / задачи CIS / роли+права AuthZ / провайдеры идентичности / стаб TLS-сертификата
|
||
- Список/получение/создание/удаление/power ВМ, оборудование, снапшоты,
|
||
клонирование, relocate, tools, идентичность/сети/питание/customization
|
||
гостя, консольные тикеты, template/unregister
|
||
- Список/получение хостов + maintenance + storage-device + сети
|
||
- Список/получение datastore + метаданные файлов
|
||
- Список сетей + создание DVS/DVPG
|
||
- CRUD для datacenter / cluster / folder (+ дети) / resource-pool
|
||
- Тегирование, content library + OVF, политики хранения (+ привязки к ВМ), привилегии
|
||
- Версия/health/сети/timesync appliance
|
||
- Стаб списка сервисов метамодели `vapi`
|
||
|
||
### DB-backed поверхность Automation (catch-all universe Broadcom)
|
||
|
||
Оставшиеся маршруты Automation API из индекса операций 9.1 зарегистрированы
|
||
и обслуживаются [`app/vsphere/rest/stub_surface.py`](../../app/vsphere/rest/stub_surface.py) против PostgreSQL:
|
||
|
||
- таблица `vsphere_api_state` (миграция `011_vsphere_api_state.sql`)
|
||
- seed через `seed_api_surface()` при каждом профиле, включая
|
||
**`demo-cluster`** / UI `POST /ui/api/demo/load`
|
||
- overlay инвентаря для оборудования ВМ (cdrom/scsi/boot/…), сетей/хранения
|
||
хоста, тегирования, content library
|
||
- PUT/PATCH сохраняются в `vsphere_api_state`; POST добавляет строки
|
||
коллекции; DELETE их удаляет
|
||
|
||
Нет маркеров `"stub": true` — зондам нужны реальные seeded-payload'ы на
|
||
мажоре 9.
|
||
|
||
## Домены SOAP (govmomi / Terraform / Pulumi / pyvmomi)
|
||
|
||
- RetrieveServiceContent (+ TaskManager / SearchIndex / GuestOperationsManager / FileManager / OvfManager)
|
||
- RetrieveProperties / RetrievePropertiesEx / **ContinueRetrievePropertiesEx** (токены пагинации; `<objects>` во множественном числе)
|
||
- PropertyCollector: цепочка предков Ancestors, однохоповый `childEntity`
|
||
ListFolder, обход ContainerView `view`
|
||
- `Folder.childType` как `ArrayOfString`; строковые свойства несут
|
||
`xsi:type="xsd:string"` (декодирование govmomi)
|
||
- `Datastore.host` как `ArrayOfDatastoreHostMount`; **environmentBrowser** у
|
||
Cluster/Host
|
||
- **QueryConfigOption** / QueryConfigOptionEx / QueryConfigOptionDescriptor / QueryConfigTarget
|
||
- CreateFilter / WaitForUpdatesEx (токены версий; пустые опросы)
|
||
- FindByInventoryPath (пути govmomi не включают корневую `Datacenters`),
|
||
FindByUuid/Dns/Ip, FindChild
|
||
- **CreateVM_Task** / CreateChildVM_Task, CreateFolder,
|
||
Power/Clone/Snapshot/Rename/Reconfig/Relocate/Destroy/Unregister/MarkAsTemplate/CustomizeVM_Task + CancelTask
|
||
- Файловые операции гостя: ListFilesInGuest,
|
||
InitiateFileTransferTo/FromGuest, DeleteFileInGuest, MakeDirectoryInGuest
|
||
- Реальные ID задач из `vsphere_tasks` (включая MoRef в `info.result` при
|
||
create/clone)
|
||
- `/sdk/vimService.wsdl`, `/sdk/about.do`, стаб `/pbm`
|
||
- Строгий по типам поиск MOR: `VirtualApp:resgroup-*` не резолвится как
|
||
обычный ResourcePool (путь CreateVM в Terraform)
|
||
|
||
## Дополнения REST для Ansible / Python-приложений
|
||
|
||
- Power ВМ возвращает `{ "task": "task-…" }` для опроса задач CIS
|
||
- Виртуальная файловая система гостя:
|
||
`/api/vcenter/vm/{vm}/guest/filesystem` (+ листинг локальной файловой
|
||
системы)
|
||
- Сессии обновления/загрузки content library для лабораторных потоков
|
||
push/pull OVF
|
||
|
||
## Legacy `/rest`
|
||
|
||
Обёртки `{ "value": … }` для
|
||
vm/host/datastore/network/datacenter/cluster/power/appliance.
|
||
|
||
## Мажоры контракта (browse в сравнении с runtime)
|
||
|
||
Hot-swap (`POST /ui/api/contract/apply?major=N`) всё ещё переключает мажор
|
||
**каталога** для просмотра/evidence в UI. **Runtime всегда обслуживает
|
||
полную зарегистрированную поверхность** глубокими обработчиками или
|
||
DB-backed стабами — известные пути никогда не получают HTTP 501 из-за
|
||
уровня версии. Уровни каталога остаются историческими только для
|
||
документации.
|
||
|
||
## Поверхности платформы (доступны в лаборатории)
|
||
|
||
Исторически они считались «отложенными»; теперь они возвращают
|
||
**непустые seeded лабораторные данные** и принимают базовые мутации:
|
||
|
||
| Область | REST | SOAP |
|
||
|---|---|---|
|
||
| NSX (tier0 / проекты / edges / VPC / подсети) | Seeded-пути Automation под `namespace-management` / `namespaces` | — |
|
||
| Supervisor / WCP | namespace, классы ВМ, сводка/идентичность supervisor, политики инфраструктуры | — |
|
||
| vSAN | Политики хранения с `policy_type: VSAN` (+ лабораторная политика RAID1) | — |
|
||
| SAML / OIDC | `GET/POST/PATCH/DELETE /api/vcenter/identity/providers` (LocalOS + OIDC + SAML) | — |
|
||
| VECS / сертификаты | TLS, CSR TLS, доверенные цепочки корней, сертификаты/запросы подписи supervisor | — |
|
||
| HttpNfcLease | `PUT/GET /nfc/{lease}/files/...` | `ImportVApp_Task`, `CreateImportSpec`, ход/завершение lease |
|
||
| Customization гостя | GET+POST `/api/vcenter/vm/{vm}/guest/customization` | `CustomizeVM_Task` |
|
||
|
||
Это всё ещё **лабораторный** заменитель (не бинарно совместимый с NSX
|
||
Manager / не настоящее хранилище VECS / не полная матрица XML устройств
|
||
Broadcom). Perf/Event/Alarm по-прежнему отвечают, но не симулируются
|
||
глубоко.
|