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

2.7 KiB

Raw Blame History

Language / Язык: English | Русский

Troubleshooting

Ready stays unavailable

Confirm Postgres: make logs / Compose health.
Run make db-migrate.
Hit /health/ready again.

Task workers may retry until migrations catch up after a late migrate.

Unexpected HTTP 501

Every registered route should have a real handler or DB-backed stub — 501 should not appear for a known path. If you see it:

Confirm you are calling the exact registered path/verb (check app/vsphere/rest/coverage.py or /docs).
501 from the optional legacy stub (ENABLE_PVE_STUB=true) is expected for undeclared PVE-style methods when CONTRACT_FALLBACK=error; it is unrelated to the vSphere surface.
Report a regression — full registry coverage is expected on the native vSphere plane.

401 / 403

Session expired (2-hour sliding TTL) or vmware-api-session-id header/cookie not sent.
Basic auth malformed on /api/session (missing header, wrong user:password base64).
Privilege denial — try administrator@vsphere.local vs readonly@vsphere.local to compare (see Authorization).

Task never finishes

Inspect /api/cis/tasks/{task}.
Check worker/simulator logs (make logs).
Verify TASK_WORKER_CONCURRENCY > 0 and database leases can be claimed.
Extremely high SIMULATION_TIME_SCALE slowdowns are unusual (higher = faster simulation); mis-set worker leases are more common culprits.

TLS / gateway failures

Use host port 443 (gateway) for TLS clients — pyvmomi, govmomi, Terraform's hashicorp/vsphere provider, Pulumi.
Set verify_ssl=False / allow_unverified_ssl=true only for the local self-signed development certificate.
Inside Compose, target simulator:8080 directly (plain HTTP, no gateway).
Seeded VM names for small are web-01, web-02, db-01, app-01, jumpbox — not Proxmox-style pve01/VMIDs.

Terraform / Pulumi / Ansible drift after reseed

Reseed replaces PostgreSQL inventory (MOIDs and VM names can change); external tool state does not update automatically. Refresh, import, or rebuild stacks after make seed.

Hot-swap "did nothing"

Catalog browse ≠ apply. Use Apply as runtime or POST /ui/api/contract/apply?major=N.
Applying a major changes the Web UI catalog / evidence view, not the live route table — the runtime always serves the full registered surface. See API versions.
Apply is process-local; a Compose restart returns to the default (major 9).

Demo unload surprised you

POST /ui/api/demo/unload clears API-created state and loads small. Re-run make seed (or load demo-cluster again) to restore a richer fixture.

2.7 KiB Raw Blame History