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.
3.8 KiB
Language / Язык: English | Русский
API surface
Request path
- Middleware assigns or forwards a request ID (
REQUEST_ID_HEADER). - FastAPI routes the request to the vSphere REST router (
/api,/rest), the SOAP router (/sdk), or (ifENABLE_PVE_STUB=true) the optional legacy stub. /api/session(or/rest/com/vmware/cis/session, or SOAPLogin) resolves a principal and issues avmware-api-session-id.require_read/require_privilege(...)dependencies check the session's roles before revealing or mutating resources.- A deep handler (core inventory/lifecycle/tagging/content/appliance logic) or the DB-backed stub surface executes against PostgreSQL-backed state.
- Long operations (power, clone, relocate, snapshot, OVF deploy) create a
durable CIS task and return
{ "task": "task-…" }.
Two REST surfaces on one registry
- Core (deep) handlers — ~104 verb+path combinations across
app/vsphere/rest/router.py,vm_ext.py,inventory_ext.py,platform_rest.py,tagging_rest.py,content_rest.py,appliance_ext.py,nfc_rest.py,tasks.py. These read and mutate the seeded inventory/tagging/content/appliance tables directly. - DB-backed stub surface —
app/vsphere/rest/stub_surface.pyanswers the remaining Broadcom Automation API operations index routes (registered fromuniverse.json) againstvsphere_api_state. GET returns live inventory-derived payloads when possible, otherwise seeded rows; PUT/PATCH persist intovsphere_api_state; POST appends collection rows; DELETE removes them. No"stub": truemarker is returned — probes see real seeded payloads.
Both surfaces share one route table; core handlers take priority over stub entries registered for the same verb+path.
Legacy /rest
app/vsphere/rest/legacy.py wraps
vm/host/datastore/network/datacenter/cluster/power/appliance reads (and VM
power) in { "value": … } envelopes for older com.vmware.vcenter.* clients.
Errors (app/vsphere/errors.py)
| Status | error_type |
Typical cause |
|---|---|---|
| 400 | invalid_argument / already_exists |
Malformed body, duplicate name |
| 401 | unauthenticated |
Missing/invalid/expired session |
| 403 | unauthorized |
Session lacks the required privilege |
| 404 | not_found |
Unknown MOID/path parameter |
| 409 | (handler-specific) | Illegal power-state transition, lock conflict |
| 501 | error |
Only reachable via the optional legacy stub's undeclared-method fallback |
All error bodies follow the vSphere Automation shape:
{ "error_type": "...", "messages": [{ "default_message": "...", "id": "...", "args": [] }] }.
Tasks
Async work (power, clone, snapshot, relocate, OVF deploy, guest customize) returns a task id. Poll:
GET /api/cis/tasks/{task}
Task rows commit in vsphere_tasks; progress is 100 once status is
SUCCEEDED/FAILED. HTTP 200/201 on the mutation request means "accepted",
not "VM already in final state". See Tasks.
Exploration
- Interactive FastAPI docs:
/docs - Web UI method inspector:
/→ catalog → method - UI helper APIs:
/ui/api/catalog,/ui/api/method,/ui/api/compatibility - Coverage registry:
app/vsphere/rest/coverage.py - Path-floor / catalog matrix:
app/vsphere/contracts/matrix.py
Compatibility endpoints
| Path | Format |
|---|---|
/ui/api/compatibility?major=N |
JSON |
See Compatibility and API coverage for the full Broadcom-universe-vs-implemented breakdown.