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.
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
**Language / Язык:** [English](compatibility-0.1.0.md) | [Русский](ru/compatibility-0.1.0.md)
|
||||
|
||||
# Compatibility report — 0.1.0
|
||||
|
||||
This report records evidence for simulator release 0.1.0 against the vSphere
|
||||
Automation API route registry (catalog majors 6–9, primary contract major 9 /
|
||||
8.0 U2). It is a limitation matrix for *quality / external integration*
|
||||
dimensions, not a claim of general vCenter/ESXi hardware compatibility.
|
||||
|
||||
For the user-facing overview see [compatibility.md](compatibility.md). Live
|
||||
machine-readable counts are always available from
|
||||
`/ui/api/compatibility?major=N` when the simulator is running.
|
||||
|
||||
## Summary (major 9 / vSphere 8.0 U2 primary contract)
|
||||
|
||||
| Level | Methods | Universe share | Evidence |
|
||||
|---|---:|---:|---|
|
||||
| Declared in universe (Broadcom operations index → route table) | 1077 | 100% | `app/vsphere/rest/universe.json` |
|
||||
| Implemented at major 9 (catalog floor) | **1077** | **100%** | `app/vsphere/contracts/matrix.py` |
|
||||
| Core deep handlers (inventory/lifecycle/tagging/content/appliance) | 104 | 9.7% | `app/vsphere/rest/coverage.py` (`CORE_IMPLEMENTED`) |
|
||||
| DB-backed stub surface (remaining registry) | ~973 | 90.3% | `app/vsphere/rest/stub_surface.py` against `vsphere_api_state` |
|
||||
| Verified / observed surface ledger | **1077** | **100%** | `evidence/vsphere-8.0.2.json` |
|
||||
|
||||
## Coverage by catalog major
|
||||
|
||||
| Major | vSphere label | Implemented | Universe | Coverage |
|
||||
|---|---|---:|---:|---:|
|
||||
| 6 | 7.0 | 31 | 1077 | 2.88% |
|
||||
| 7 | 7.0 U3 | 77 | 1077 | 7.15% |
|
||||
| 8 | 8.0 | 103 | 1077 | 9.56% |
|
||||
| 9 | 8.0 U2 | 1077 | 1077 | 100.00% |
|
||||
|
||||
**Implemented** here is a catalog-floor score for Web UI browse and evidence
|
||||
reports, regenerated with `make evidence` / `make vsphere-bundles` and
|
||||
guarded by `tests/compatibility/test_verified_surface.py`. It does **not**
|
||||
gate live traffic — see [API surface](api-surface.md) for why runtime always
|
||||
serves the registered route regardless of the applied major.
|
||||
|
||||
## Implemented surface (high level)
|
||||
|
||||
- **Session**: `/api/session`, `/rest/com/vmware/cis/session`, SOAP
|
||||
`Login`/`Logout` — all durable in PostgreSQL (`vsphere_sessions`,
|
||||
`vsphere_credentials`).
|
||||
- **Inventory**: VM/host/datastore/network/datacenter/cluster/folder/resource-pool
|
||||
list+get, plus create/delete for datacenter/cluster/folder/resource-pool.
|
||||
- **VM lifecycle**: create, delete, power, hardware (CPU/memory/disk/NIC/boot),
|
||||
snapshots, clone, relocate, guest identity/networking/power/customization,
|
||||
console tickets, tools.
|
||||
- **Tasks**: `/api/cis/tasks`, real ids from `vsphere_tasks`, SOAP task MoRefs.
|
||||
- **Tagging / content library**: categories, tags, associations, libraries,
|
||||
library items, update/download sessions, OVF deploy.
|
||||
- **Authorization**: privileges, roles, permissions CRUD, identity providers.
|
||||
- **Appliance**: version, health, networking (hostname/DNS), timesync.
|
||||
- **SOAP / VIM**: RetrieveServiceContent, PropertyCollector
|
||||
(RetrieveProperties/Ex, ContinueRetrievePropertiesEx, CreateFilter,
|
||||
WaitForUpdatesEx), FindBy* / FindChild, CreateVM_Task and friends, guest
|
||||
file operations, HttpNfcLease import flow, WSDL stub.
|
||||
- **Platform lab surfaces**: seeded (non-binary-compatible) NSX/Supervisor/vSAN/
|
||||
SAML-OIDC/VECS-cert stand-ins — see [API coverage](api-coverage.md) for the
|
||||
exact list and caveats.
|
||||
|
||||
## Persistence principle
|
||||
|
||||
Every create/update/delete path writes to PostgreSQL (tables and/or the
|
||||
`vsphere_api_state` catch-all). Secrets may be stored but must not be echoed
|
||||
on GET. User-facing "not supported in the emulator" errors are forbidden for
|
||||
registered paths — see `.cursor/rules/durable-simulator.mdc`.
|
||||
|
||||
## Known limitations
|
||||
|
||||
| Area | Current behavior |
|
||||
|---|---|
|
||||
| External systems | NSX/LDAP/SAML/OIDC/ACME do not contact real remotes; state is simulated locally |
|
||||
| TLS | Local nginx gateway with a checked-in self-signed development key only |
|
||||
| Client certification | pyvmomi/govmomi-style SOAP smoke + Ansible/Terraform/Pulumi cookbooks; not a formal certification suite for every provider version |
|
||||
| Provider smoke | The `pulumi-vsphere` suite under `pulumi-tests/` (`make pulumi-tests`) exercises SOAP-backed inventory/VM/tag resources with nonempty export checks; semantic depth still varies (deep handlers vs DB-backed stubs) |
|
||||
|
||||
Full registry coverage at major 9 means HTTP 501 "handler pending" should not
|
||||
appear for any route in the simulator's registry. Compatibility *quality*
|
||||
(exact vSphere edge-case parity) still deepens with tests and observation.
|
||||
|
||||
When importing a refreshed Broadcom operations index dump: regenerate
|
||||
`universe.json` (`make vsphere-universe`), regenerate bundles/evidence
|
||||
(`make vsphere-bundles`, `make evidence`), run
|
||||
`pytest tests/compatibility/test_verified_surface.py`, and commit the updated
|
||||
`evidence/vsphere-*.json` ledgers.
|
||||
Reference in New Issue
Block a user