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,74 @@
+**Language / Язык:** [English](compatibility.md) | [Русский](ru/compatibility.md)
+
+# Compatibility
+
+This document explains how the simulator claims compatibility with the
+vSphere Automation API across catalog majors **6–9**. Prefer live reports
+when the process is running.
+
+## Live reports
+
+| URL | Format |
+|---|---|
+| `/ui/api/compatibility?major=N` | JSON |
+
+The Web UI also exposes a compatibility panel driven by this endpoint.
+
+## Registry vs verified surface coverage
+
+| Major | vSphere label | Implemented / universe | Coverage |
+|---|---|---:|---:|
+| 6 | 7.0 | 31 / 1077 | 2.9% |
+| 7 | 7.0 U3 | 77 / 1077 | 7.2% |
+| 8 | 8.0 | 103 / 1077 | 9.6% |
+| 9 | 8.0 U2 (Automation 9.1 surface) | **1077 / 1077** | **100%** |
+
+- **Universe** — unique verb+path routes derived from the public
+  [vSphere Automation API operations index](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/operation-index/)
+  (1348 documented operations → ~1037 unique routes → 1077 registered in this
+  simulator's route table, since some paths back multiple named operations).
+- **Implemented (per major)** — routes whose catalog floor
+  (`app/vsphere/contracts/matrix.py`) is at or below that major. This is a
+  **catalog/documentation** score, not a live-traffic gate.
+- **Runtime** — regardless of the applied catalog major, every registered
+  route is always served by its real handler (104 deep handlers) or the
+  DB-backed stub surface. See [API surface](api-surface.md).
+
+After **Apply as runtime** (`POST /ui/api/contract/apply?major=N`), the live
+report loads that major's ledger (`evidence/vsphere-{version}.json`) so the
+Web UI compatibility panel reflects the selected major.
+
+## Evidence dimensions
+
+Per-major ledgers in `evidence/vsphere-{version}.json` record `declared`,
+`implemented`, `observed`, and `verified` counts plus per-HTTP-verb and
+per-domain (`auth_session`, `inventory`, …) breakdowns. Regenerate with:
+
+```bash
+make evidence          # app/evidence_gen.py
+make vsphere-bundles   # stub OpenAPI matrices + evidence ledgers together
+```
+
+Executable backing for those claims:
+
+| Suite | Role |
+|---|---|
+| `tests/compatibility/test_verified_surface.py` | hot-swap + ledger drift + score gates |
+| `tests/compatibility/test_group_smoke.py` | representative REST group mutations with PostgreSQL |
+| `tests/compatibility/test_vsphere_pyvmomi.py` | external pyvmomi SOAP smoke |
+| `tests/integration/test_vsphere_full_api.py` | broad REST/SOAP integration coverage |
+
+Additional cookbooks under [`examples/`](../examples/README.md) and the
+`pulumi-vsphere` lab suite under [`pulumi-tests/`](../pulumi-tests/README.md)
+(`make pulumi-tests`) are manual or CI-optional depending on the stack.
+
+## Known behavioural limits
+
+| Area | Behaviour |
+|---|---|
+| External systems | NSX Manager, live LDAP/SAML/OIDC IdPs, and ACME directories do not contact real remotes; seeded/local state only |
+| TLS | Local self-signed development gateway only (Compose); use your own certs / cert-manager for real deployments |
+| Hypervisor | No real ESXi/KVM execution; no binary NFC uploads |
+| Observation corpus | Sanitized real-vCenter observation data remains limited; deep semantic parity is verified path-by-path via the suites above, not by exhaustive production diffing |
+
+Historical release notes: [compatibility-0.1.0.md](compatibility-0.1.0.md).