inecs
f8d3cbdd59
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.
136 lines
7.5 KiB
Markdown
136 lines
7.5 KiB
Markdown
**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.
|