DevOpsTools/vmware-api-simulator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
00315af0609d24c9aebf6dd9c74603b1b4d25b55
vmware-api-simulator/docs/api-coverage.md
T
inecs f8d3cbdd59 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

7.5 KiB
Raw Blame History

Language / Язык: English | Русский

vSphere API coverage matrix

Auto-oriented registry: app/vsphere/rest/coverage.py.
Broadcom universe stubs: app/vsphere/rest/universe.json (from the public operations index).
Per-major floors + stub OpenAPI bundles: 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)

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:

python scripts/generate_vsphere_universe.py
make vsphere-bundles

Refresh live stats / regenerate artifacts:

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 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.

Reference in New Issue View Git Blame Copy Permalink