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.
This commit is contained in:
@@ -0,0 +1,175 @@
|
||||
**Language / Язык:** [English](getting-started.md) | [Русский](ru/getting-started.md)
|
||||
|
||||
# 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](#1a-published-image-docker-hub) | Fastest lab using `inecs/vmware-api-simulator` |
|
||||
| [Helm / Kubernetes](kubernetes.md) | Cluster install with Ingress + Let's Encrypt |
|
||||
| [Development checkout](#1b-development-checkout) | Contribute / bind-mount source |
|
||||
|
||||
## 1a. Published image (Docker Hub)
|
||||
|
||||
Uses [`docker-compose.release.yml`](../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.
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
IMAGE_TAG=0.1.0 docker compose -f docker-compose.release.yml up -d --wait
|
||||
```
|
||||
|
||||
Make helpers (git checkout):
|
||||
|
||||
```bash
|
||||
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](#2-wait-until-ready).
|
||||
|
||||
## 1b. Development checkout
|
||||
|
||||
```bash
|
||||
make install
|
||||
make up
|
||||
```
|
||||
|
||||
Services (see [Ports](ports.md) 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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](seed-profiles.md) for other sizes.
|
||||
|
||||
## 4. Check the API version
|
||||
|
||||
```bash
|
||||
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](api-versions.md).
|
||||
|
||||
## 5. Authenticate
|
||||
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
curl -sk -H "vmware-api-session-id: $SID" https://localhost/api/vcenter/vm
|
||||
```
|
||||
|
||||
Details: [Authentication](authentication.md).
|
||||
|
||||
## 6. List VMs and power one on
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
curl -sk -H "vmware-api-session-id: $SID" \
|
||||
"https://localhost/api/cis/tasks/${TASK_ID}" | jq .
|
||||
```
|
||||
|
||||
## 7. Open the Web UI
|
||||
|
||||
Visit [https://localhost/](https://localhost/) for the interactive
|
||||
console, endpoint catalog (vSphere majors 6–9), compatibility view, runtime
|
||||
contract apply, and demo-cluster controls. See [Web UI](web-ui.md) for
|
||||
light/dark theme screenshots and the full feature list.
|
||||
|
||||
## 8. Try a client library
|
||||
|
||||
```bash
|
||||
# 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](clients.md) and [`examples/`](../examples/README.md).
|
||||
|
||||
## 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](configuration.md) — env vars, workers, seed sizing
|
||||
- [API versions](api-versions.md) — hot-swap catalog majors 6–9
|
||||
- [Clients](clients.md) — Python, Ansible, Terraform, Pulumi
|
||||
- [Operations](operations.md) — reseed, migrate, upgrades
|
||||
Reference in New Issue
Block a user