Initial commit: VMware vSphere API simulator scaffold.

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.
2026-07-18 04:42:11 +03:00
commit f8d3cbdd59
422 changed files with 361335 additions and 0 deletions
@@ -0,0 +1,87 @@
+**Language / Язык:** [English](../compatibility-0.1.0.md) | [Русский](compatibility-0.1.0.md)
+
+# Отчёт совместимости — 0.1.0
+
+Этот отчёт фиксирует evidence для релиза симулятора 0.1.0 относительно реестра
+маршрутов vSphere Automation API (catalog majors 6–9, основной contract major 9 /
+8.0 U2). Это матрица ограничений по измерениям *качества / внешней интеграции*,
+а не утверждение общей аппаратной совместимости с vCenter/ESXi.
+
+Пользовательский обзор — [compatibility.md](compatibility.md). Живые
+машиночитаемые счётчики всегда доступны из
+`/ui/api/compatibility?major=N`, когда симулятор запущен.
+
+## Сводка (major 9 / основной контракт vSphere 8.0 U2)
+
+| Уровень | Methods | Доля universe | Evidence |
+|---|---:|---:|---|
+| Declared in universe (Broadcom operations index → route table) | 1077 | 100% | `app/vsphere/rest/universe.json` |
+| Implemented at major 9 (catalog floor) | **1077** | **100%** | `app/vsphere/contracts/matrix.py` |
+| Core deep handlers (inventory/lifecycle/tagging/content/appliance) | 104 | 9.7% | `app/vsphere/rest/coverage.py` (`CORE_IMPLEMENTED`) |
+| DB-backed stub surface (остальной реестр) | ~973 | 90.3% | `app/vsphere/rest/stub_surface.py` против `vsphere_api_state` |
+| Verified / observed surface ledger | **1077** | **100%** | `evidence/vsphere-8.0.2.json` |
+
+## Покрытие по catalog major
+
+| Major | Метка vSphere | Implemented | Universe | Coverage |
+|---|---|---:|---:|---:|
+| 6 | 7.0 | 31 | 1077 | 2.88% |
+| 7 | 7.0 U3 | 77 | 1077 | 7.15% |
+| 8 | 8.0 | 103 | 1077 | 9.56% |
+| 9 | 8.0 U2 | 1077 | 1077 | 100.00% |
+
+**Implemented** здесь — оценка catalog-floor для browse в Web UI и
+evidence-отчётов, перегенерируется через `make evidence` / `make vsphere-bundles`
+и защищена `tests/compatibility/test_verified_surface.py`. Она **не**
+гейтит живой трафик — почему runtime всегда обслуживает зарегистрированный
+маршрут независимо от применённого major, см. [Поверхность API](api-surface.md).
+
+## Реализованная поверхность (верхний уровень)
+
+- **Session**: `/api/session`, `/rest/com/vmware/cis/session`, SOAP
+  `Login`/`Logout` — всё устойчиво в PostgreSQL (`vsphere_sessions`,
+  `vsphere_credentials`).
+- **Inventory**: list+get для VM/host/datastore/network/datacenter/cluster/folder/resource-pool,
+  плюс create/delete для datacenter/cluster/folder/resource-pool.
+- **VM lifecycle**: create, delete, power, hardware (CPU/memory/disk/NIC/boot),
+  snapshots, clone, relocate, guest identity/networking/power/customization,
+  console tickets, tools.
+- **Tasks**: `/api/cis/tasks`, реальные ids из `vsphere_tasks`, SOAP task MoRefs.
+- **Tagging / content library**: categories, tags, associations, libraries,
+  library items, update/download sessions, OVF deploy.
+- **Authorization**: privileges, roles, permissions CRUD, identity providers.
+- **Appliance**: version, health, networking (hostname/DNS), timesync.
+- **SOAP / VIM**: RetrieveServiceContent, PropertyCollector
+  (RetrieveProperties/Ex, ContinueRetrievePropertiesEx, CreateFilter,
+  WaitForUpdatesEx), FindBy* / FindChild, CreateVM_Task и связанные, guest
+  file operations, HttpNfcLease import flow, WSDL stub.
+- **Platform lab surfaces**: seeded (не бинарно совместимые) stand-in'ы
+  NSX/Supervisor/vSAN/SAML-OIDC/VECS-cert — точный список и оговорки в
+  [Покрытие API](api-coverage.md).
+
+## Принцип персистентности
+
+Каждый путь create/update/delete пишет в PostgreSQL (таблицы и/или catch-all
+`vsphere_api_state`). Секреты могут храниться, но не должны отдаваться на GET.
+Пользовательские ошибки «not supported in the emulator» для зарегистрированных
+путей запрещены — см. `.cursor/rules/durable-simulator.mdc`.
+
+## Известные ограничения
+
+| Область | Текущее поведение |
+|---|---|
+| Внешние системы | NSX/LDAP/SAML/OIDC/ACME не обращаются к реальным remotes; состояние симулируется локально |
+| TLS | Локальный nginx gateway только с закоммиченным self-signed development key |
+| Сертификация клиентов | SOAP smoke в стиле pyvmomi/govmomi + cookbook'и Ansible/Terraform/Pulumi; не формальный certification suite для каждой версии провайдера |
+| Smoke провайдера | Набор `pulumi-vsphere` в `pulumi-tests/` (`make pulumi-tests`) гоняет SOAP inventory/VM/tag с проверкой непустых export'ов; семантическая глубина по-прежнему разная (deep handlers vs DB-backed stubs) |
+
+Полное покрытие реестра на major 9 означает, что HTTP 501 «handler pending»
+не должен появляться ни для одного маршрута в реестре симулятора. *Качество*
+совместимости (точный паритет крайних случаев vSphere) по-прежнему углубляется
+тестами и observation.
+
+При импорте обновлённого дампа Broadcom operations index: перегенерируйте
+`universe.json` (`make vsphere-universe`), bundles/evidence
+(`make vsphere-bundles`, `make evidence`), запустите
+`pytest tests/compatibility/test_verified_surface.py` и закоммитьте обновлённые
+ledgers `evidence/vsphere-*.json`.