vmware-api-simulator/docs/ru/api-coverage.md

Language / Язык: English | Русский

Матрица покрытия vSphere API

Реестр, ориентированный на автоматизацию: app/vsphere/rest/coverage.py. Стабы universe от Broadcom: app/vsphere/rest/universe.json (из публичного индекса операций). Уровни по мажорам + бандлы стаб-OpenAPI: app/vsphere/contracts/matrix.py → contracts/vsphere/<version>/manifest.json.

Broadcom в сравнении с этим симулятором

Публичный источник (собран скрапингом): Индекс операций vSphere Automation API (9.1 Latest)

Поверхность	Количество	Примечания
Индекс операций 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 после обновления дампа индекса:

python scripts/generate_vsphere_universe.py
make vsphere-bundles

Обновление живой статистики / регенерация артефактов:

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