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

5.1 KiB

Raw Blame History

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

Getting started

Bring up a local vSphere laboratory, authenticate, and exercise a first read/mutation cycle against the simulator.

Prerequisites

Docker and Docker Compose
make (optional but used by the documented commands)

Python, linters, and tests run inside containers. You do not need a local Python toolchain for day-to-day use.

Choose a path

Path	When to use
Published image	Fastest lab using `inecs/vmware-api-simulator`
Helm / Kubernetes	Cluster install with Ingress + Let's Encrypt
Development checkout	Contribute / bind-mount source

1a. Published image (Docker Hub)

Uses docker-compose.release.yml — PostgreSQL + runtime simulator + HTTPS gateway from Hub. No source build required, but you must run Compose from a checkout of this repository so docker/gateway/ and docker/tls/ bind-mounts resolve. Seed runs automatically after the simulator is healthy.

# from a git checkout of this repository (needs docker/gateway + docker/tls)
docker compose -f docker-compose.release.yml pull
docker compose -f docker-compose.release.yml up -d --wait

Pin a version:

IMAGE_TAG=0.1.0 docker compose -f docker-compose.release.yml up -d --wait

Make helpers (git checkout):

make release-up
# optional re-seed: make release-seed PROFILE=small

Host port	Service
`443`	HTTPS gateway (primary vCenter entry)
`80`	HTTP lab face
`5434`	PostgreSQL (localhost only)

Migrations run automatically via the migrate one-shot service.

Then continue from Wait until ready.

1b. Development checkout

make install
make up

Services (see Ports for the full picture):

Host port	Service
`443`	HTTPS gateway (nginx) → simulator
`80`	HTTP lab face
`5434`	PostgreSQL (localhost only)

Migrations apply automatically before the simulator becomes ready. The internal FastAPI process listens on 8080 and is not published to the host.

2. Wait until ready

curl -sk https://localhost/health/live
curl -sk https://localhost/health/ready

/health/ready returns HTTP 503 until PostgreSQL is reachable and the latest packaged migration is applied.

3. Seed a profile

make seed                          # default: large — 10 hosts / 1000 VMs
VSPHERE_PROFILE=small make seed

small creates a 3-host cluster with five named VMs (web-01, web-02, db-01, app-01, jumpbox), datastores, a standard portgroup, and the four lab principals. See Seed profiles for other sizes.

4. Check the API version

curl -sk https://localhost/api/appliance/system/version | jq .

The cold-start catalog major defaults to 9 (vSphere 8.0 U2 / Automation 9.1 surface) in Docker Compose. Browse or hot-swap majors 6–9 from the Web UI or API versions.

5. Authenticate

SID=$(curl -sk -u 'administrator@vsphere.local:VMware1!' \
  -X POST https://localhost/api/session | tr -d '"')
echo "$SID"

SID is the vmware-api-session-id. Send it on every subsequent call as a header (or rely on the cookie the login response also sets):

curl -sk -H "vmware-api-session-id: $SID" https://localhost/api/vcenter/vm

Details: Authentication.

6. List VMs and power one on

curl -sk -H "vmware-api-session-id: $SID" \
  https://localhost/api/vcenter/vm | jq .

curl -sk -X POST -H "vmware-api-session-id: $SID" \
  "https://localhost/api/vcenter/vm/vm-104/power?action=start" | jq .

Power actions and other long-running operations return a CIS task id. Poll until the task finishes:

curl -sk -H "vmware-api-session-id: $SID" \
  "https://localhost/api/cis/tasks/${TASK_ID}" | jq .

7. Open the Web UI

Visit https://localhost/ for the interactive console, endpoint catalog (vSphere majors 6–9), compatibility view, runtime contract apply, and demo-cluster controls. See Web UI for light/dark theme screenshots and the full feature list.

8. Try a client library

# from the repository root after make up + seed
python examples/python/vsphere_rest_smoke.py https://localhost
python examples/python/vsphere_soap_smoke.py https://localhost

More stacks: Clients and examples/.

You're done when…

/health/ready returns {"status": "ok"} (or equivalent OK body)
/api/appliance/system/version reports the active catalog major's version
Session login succeeds for administrator@vsphere.local
/api/vcenter/vm lists the seeded VMs
A power action returns a task id that reaches SUCCEEDED

Next steps

Configuration — env vars, workers, seed sizing
API versions — hot-swap catalog majors 6–9
Clients — Python, Ansible, Terraform, Pulumi
Operations — reseed, migrate, upgrades

5.1 KiB Raw Blame History Unescape Escape