77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
**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` / `big`) build a deterministic cluster —
|
||
default **large** is 10 hosts / **1000 VMs** (`big` = 20 / 2000).
|
||
|
||
## 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)
|