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,77 @@
+**Language / Язык:** [English](../architecture.md) | [Русский](architecture.md)
+
+# Архитектура
+
+## Цели
+
+`vmware-api-simulator` — stateful лабораторный эмулятор vSphere (Automation REST +
+VIM SOAP). Главная цель дизайна — **практическая совместимость клиентов**:
+сессии, inventory, жизненный цикл VM, обходы PropertyCollector, задачи,
+stubs tagging/content library и роли AuthZ реализованы поверх большого
+синтетического datastore, чтобы инструменты вроде curl, govc-подобных
+потоков, pyvmomi и Terraform могли прогонять типовые пути без реального
+vCenter.
+
+Catalog majors **6–9** соответствуют floors vSphere 7.0 / 7.0U3 / 8.0 / 8.0U2.
+Hot-swap меняет каталог только для browse/evidence в Web UI — он **не**
+гейтит живые маршруты. Опциональный stub Proxmox `/api2/*` остаётся за
+`ENABLE_PVE_STUB` (по умолчанию выключен).
+
+## Контекст системы
+
+```mermaid
+flowchart LR
+    Client["API clients<br/>pyvmomi / Terraform / govc / REST SDKs"]
+    Admin["Lab operator"]
+    UI["Web lab UI"]
+    API["FastAPI application"]
+    Gateway["HTTPS gateway :443"]
+    Contract["vSphere contract matrix"]
+    Domain["vsphere domain + inventory"]
+    DB[(PostgreSQL)]
+    Obs["Logs / Prometheus / OpenTelemetry"]
+
+    Client -->|"/api /rest /sdk"| Gateway
+    Gateway --> API
+    UI --> Gateway
+    Admin -->|"seed / migrate"| API
+    API --> Contract
+    API --> Domain
+    Domain --> DB
+    API --> Obs
+```
+
+## Плоскости
+
+| Плоскость | Путь | Заметки |
+|---|---|---|
+| Automation REST | `/api`, `/rest` | Заголовок сессии `vmware-api-session-id` |
+| VIM SOAP | `/sdk` | Подмножество PropertyCollector + VM tasks |
+| Lab UI helpers | `/ui/api/*` | Каталог, demo seed, совместимость |
+| Опциональный PVE stub | `/api2/*` | Выкл., пока `ENABLE_PVE_STUB=true` |
+
+## Модель данных
+
+Inventory живёт в `vsphere_objects` (MOID, типы, props JSON, parent-ссылки).
+Sessions, credentials, tasks, tags, libraries, snapshots и permissions —
+соседние таблицы (миграции `009_vsphere.sql`, `010_vsphere_platform.sql`).
+DB-backed Automation stubs используют `vsphere_api_state` (`011`); сессии
+transfer content library и строки HttpNfcLease — в `vsphere_transfer_sessions` /
+`vsphere_nfc_leases` (`012`); views/tokens PropertyCollector и console tickets —
+в `vsphere_pc_state` / `vsphere_console_tickets` (`013`).
+
+Профили seed (`small` / `large` / `demo-cluster`) строят детерминированный
+кластер — по умолчанию **large** это ~10 hosts / **1000 VMs**.
+
+## AuthZ
+
+Credentials отображаются в roles → privilege sets. Мутирующие обработчики
+используют `require_privilege(...)`; пути чтения — `require_read`. SOAP Login
+выдаёт cookie, совместимый с VIM-сессиями.
+
+## Связанные документы
+
+- [Покрытие API](api-coverage.md)
+- [Аутентификация](authentication.md)
+- [Web UI](web-ui.md)
+- [Клиенты](clients.md)