vmware-api-simulator/docs/getting-started.md

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 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