**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 по-прежнему отвечают, но не симулируются
глубоко.