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,76 @@
+**Language / Язык:** [English](architecture.md) | [Русский](ru/architecture.md)
+
+# Architecture
+
+## Goals
+
+`vmware-api-simulator` is a stateful vSphere lab emulator (Automation REST + VIM SOAP).
+The primary design goal is **practical client compatibility**: sessions, inventory,
+VM lifecycle, PropertyCollector walks, tasks, tagging/content library stubs, and
+AuthZ roles are implemented against a large synthetic datastore so tools like curl,
+govc-style flows, pyvmomi, and Terraform can exercise common paths without a real
+vCenter.
+
+Catalog majors **6–9** map to vSphere 7.0 / 7.0U3 / 8.0 / 8.0U2 floors. Hot-swap
+changes the catalog used for Web UI browse/evidence only — it does **not** gate
+live routes. Optional Proxmox `/api2/*` stub remains behind `ENABLE_PVE_STUB`
+(off by default).
+
+## System context
+
+```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
+```
+
+## Planes
+
+| Plane | Path | Notes |
+|---|---|---|
+| Automation REST | `/api`, `/rest` | Session header `vmware-api-session-id` |
+| VIM SOAP | `/sdk` | PropertyCollector subset + VM tasks |
+| Lab UI helpers | `/ui/api/*` | Catalog, demo seed, compatibility |
+| Optional PVE stub | `/api2/*` | Off unless `ENABLE_PVE_STUB=true` |
+
+## Data model
+
+Inventory lives in `vsphere_objects` (MOIDs, types, props JSON, parent links).
+Sessions, credentials, tasks, tags, libraries, snapshots, and permissions are
+sibling tables (migrations `009_vsphere.sql`, `010_vsphere_platform.sql`).
+DB-backed Automation stubs use `vsphere_api_state` (`011`); content-library
+transfer sessions and HttpNfcLease rows live in `vsphere_transfer_sessions` /
+`vsphere_nfc_leases` (`012`); PropertyCollector views/tokens and console
+tickets persist in `vsphere_pc_state` / `vsphere_console_tickets` (`013`).
+
+Seed profiles (`small` / `large` / `demo-cluster`) build a deterministic cluster —
+default **large** is ~10 hosts / **1000 VMs**.
+
+## AuthZ
+
+Credentials map to roles → privilege sets. Mutate handlers use
+`require_privilege(...)`; read paths use `require_read`. SOAP Login issues a cookie
+compatible with VIM sessions.
+
+## Related docs
+
+- [API coverage](api-coverage.md)
+- [Authentication](authentication.md)
+- [Web UI](web-ui.md)
+- [Clients](clients.md)