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,135 @@
+**Language / Язык:** [English](api-coverage.md) | [Русский](ru/api-coverage.md)
+
+# vSphere API coverage matrix
+
+Auto-oriented registry: [`app/vsphere/rest/coverage.py`](../app/vsphere/rest/coverage.py).  
+Broadcom universe stubs: [`app/vsphere/rest/universe.json`](../app/vsphere/rest/universe.json) (from the public operations index).  
+Per-major floors + stub OpenAPI bundles: [`app/vsphere/contracts/matrix.py`](../app/vsphere/contracts/matrix.py) → `contracts/vsphere/<version>/manifest.json`.
+
+## Broadcom vs this simulator
+
+Public source (scraped): [vSphere Automation API Operations Index (9.1 Latest)](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/operation-index/)
+
+| Surface | Count | Notes |
+|---|---:|---|
+| Broadcom Operations Index | **1348** | GET 628 / POST 422 / DELETE 114 / PUT 93 / PATCH 91 |
+| Generated unique `verb + path` routes | **~1037** | Same HTTP path can back several named ops (`?action=…`, `$Task`) |
+| Simulator registry (core + stubs + `/rest`) | **1077** | Core deep handlers overwrite stub entries on the same path |
+| Core deep handlers | **104** | Seeded inventory / lifecycle / authz behaviour |
+| DB-backed surface rows (`vsphere_api_state`) | **~540+** | Seeded for every GET `/api` route + lab extras |
+
+Regenerate universe after refreshing the index dump:
+
+```bash
+python scripts/generate_vsphere_universe.py
+make vsphere-bundles
+```
+
+Refresh live stats / regenerate artifacts:
+
+```bash
+curl -sk https://localhost/ui/api/compatibility?major=9
+make vsphere-surface
+python scripts/write_vsphere_bundles.py
+python scripts/write_vsphere_evidence.py
+```
+
+| Major | Label | Implemented / universe | Coverage | Notes |
+|---|---|---:|---:|---|
+| 6 | vSphere 7.0 | 31 / 1077 | 2.9% | Catalog/evidence floor only |
+| 7 | vSphere 7.0 U3 | 77 / 1077 | 7.2% | Catalog/evidence floor only |
+| 8 | vSphere 8.0 | 103 / 1077 | 9.6% | Catalog/evidence floor only |
+| 9 | vSphere 8.0 U2 / Automation 9.1 surface | **1077 / 1077** | **100%** | Deep handlers + DB-backed Broadcom surface |
+
+Numbers come from `GET /ui/api/compatibility?major=N` and `evidence/vsphere-*.json` (`make vsphere-bundles`).
+
+Hot-swap (`POST /ui/api/contract/apply?major=N`) changes the **catalog** major used by the Web UI / evidence reports. **Runtime always serves the full registered surface** — known paths are never HTTP 501’d by version floor.
+
+## Planes
+
+| Plane | Default | Notes |
+|---|---|---|
+| Native REST `/api`, `/rest` | on | Primary lab surface |
+| Native SOAP `/sdk` | on | PropertyCollector subset + VM tasks |
+| Proxmox `/api2/*` stub | **off** (`ENABLE_PVE_STUB=false`) | Optional legacy |
+
+## Auth & synthetic data
+
+| Item | Detail |
+|---|---|
+| Users | `administrator`, `readonly`, `operator`, `vmadmin` `@vsphere.local` / `VMware1!` |
+| AuthZ | Role → privilege gate on mutate endpoints (403 `unauthorized`) |
+| Seed `large` | 10 hosts, **1000 VMs**, 4 datastores, DVS, folders, permissions |
+| Seed `demo-cluster` | 20 hosts, 1000 VMs (UI demo load) |
+| Seed `small` | 3 hosts, 5 named VMs (tests) |
+
+## REST domains
+
+### Deep (core) at major 9
+
+- Session / CIS tasks / AuthZ roles+permissions / identity providers / TLS cert stub
+- VM list/get/create/delete/power, hardware, snapshots, clone, relocate, tools, guest identity/networking/power/customization, console tickets, template/unregister
+- Host list/get + maintenance + storage-device + networking
+- Datastore list/get + file metadata
+- Network list + DVS/DVPG create
+- Datacenter / cluster / folder (+children) / resource-pool CRUD
+- Tagging, content library + OVF, storage policies (+ VM associations), privileges
+- Appliance version/health/networking/timesync
+- `vapi` metamodel service list stub
+
+### DB-backed Automation surface (Broadcom universe catch-all)
+
+Remaining Automation API routes from the 9.1 operations index are registered and answered by [`app/vsphere/rest/stub_surface.py`](../app/vsphere/rest/stub_surface.py) against PostgreSQL:
+
+- table `vsphere_api_state` (migration `011_vsphere_api_state.sql`)
+- seeded by `seed_api_surface()` on every profile including **`demo-cluster`** / UI `POST /ui/api/demo/load`
+- inventory overlay for VM hardware (cdrom/scsi/boot/…), host networking/storage, tagging, content libraries
+- PUT/PATCH persist into `vsphere_api_state`; POST appends collection rows; DELETE removes them
+
+No `"stub": true` markers — probes require real seeded payloads on major 9.
+
+## SOAP domains (govmomi / Terraform / Pulumi / pyvmomi)
+
+- RetrieveServiceContent (+ TaskManager / SearchIndex / GuestOperationsManager / FileManager / OvfManager)
+- RetrieveProperties / RetrievePropertiesEx / **ContinueRetrievePropertiesEx** (pagination tokens; `<objects>` plural)
+- PropertyCollector: parent-chain Ancestors, one-hop `childEntity` ListFolder, ContainerView `view` traversal
+- Folder.childType as `ArrayOfString`; string props carry `xsi:type="xsd:string"` (govmomi decode)
+- Datastore.host as `ArrayOfDatastoreHostMount`; Cluster/Host **environmentBrowser**
+- **QueryConfigOption** / QueryConfigOptionEx / QueryConfigOptionDescriptor / QueryConfigTarget
+- CreateFilter / WaitForUpdatesEx (version tokens; empty polls)
+- FindByInventoryPath (govmomi paths omit root `Datacenters`), FindByUuid/Dns/Ip, FindChild
+- **CreateVM_Task** / CreateChildVM_Task, CreateFolder, Power/Clone/Snapshot/Rename/Reconfig/Relocate/Destroy/Unregister/MarkAsTemplate/CustomizeVM_Task + CancelTask
+- Guest file ops: ListFilesInGuest, InitiateFileTransferTo/FromGuest, DeleteFileInGuest, MakeDirectoryInGuest
+- Real task IDs from `vsphere_tasks` (including `info.result` MoRef on create/clone)
+- `/sdk/vimService.wsdl`, `/sdk/about.do`, `/pbm` stub
+- Type-strict MOR lookup: `VirtualApp:resgroup-*` does not resolve a plain ResourcePool (Terraform CreateVM path)
+
+## REST extras for Ansible / Python apps
+
+- VM power returns `{ "task": "task-…" }` for CIS task polling
+- Guest virtual filesystem: `/api/vcenter/vm/{vm}/guest/filesystem` (+ local-filesystem listing)
+- Content library update/download sessions for OVF push/pull lab flows
+
+## Legacy `/rest`
+
+`{ "value": … }` wrappers for vm/host/datastore/network/datacenter/cluster/power/appliance.
+
+## Contract majors (browse vs runtime)
+
+Hot-swap (`POST /ui/api/contract/apply?major=N`) still switches the **catalog** major for UI browse/evidence. **Runtime always serves the full registered surface** with deep handlers or DB-backed stubs — known paths are never HTTP 501’d by version floor. Catalog floors remain historical for documentation only.
+
+## Platform surfaces (lab-available)
+
+These were historically “deferred”; they now return **non-empty seeded lab data** and accept basic mutate:
+
+| Area | REST | SOAP |
+|---|---|---|
+| NSX (tier0 / projects / edges / VPC / subnets) | Seeded Automation paths under `namespace-management` / `namespaces` | — |
+| Supervisor / WCP | namespaces, VM classes, supervisor summary/identity, infra policies | — |
+| vSAN | Storage policies with `policy_type: VSAN` (+ RAID1 lab policy) | — |
+| SAML / OIDC | `GET/POST/PATCH/DELETE /api/vcenter/identity/providers` (LocalOS + OIDC + SAML) | — |
+| VECS / certs | TLS, TLS CSR, trusted-root-chains, supervisor certs/signing-requests | — |
+| HttpNfcLease | `PUT/GET /nfc/{lease}/files/...` | `ImportVApp_Task`, `CreateImportSpec`, lease progress/complete |
+| Guest customization | GET+POST `/api/vcenter/vm/{vm}/guest/customization` | `CustomizeVM_Task` |
+
+This is still a **lab-grade** stand-in (not a binary-compatible NSX Manager / real VECS store / full Broadcom device XML matrix). Perf/Event/Alarm remain answered but not deeply simulated.