Files

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

3.8 KiB

Raw Blame History

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 (if ENABLE_PVE_STUB=true) the optional legacy stub.
/api/session (or /rest/com/vmware/cis/session, or SOAP Login) resolves a principal and issues a vmware-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.py answers the remaining Broadcom Automation API operations index routes (registered from universe.json) against vsphere_api_state. GET returns live inventory-derived payloads when possible, otherwise seeded rows; PUT/PATCH persist into vsphere_api_state; POST appends collection rows; DELETE removes them. No "stub": true marker 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.

3.8 KiB Raw Blame History