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

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.

2.7 KiB Raw Permalink Blame History Unescape Escape