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
commit f8d3cbdd59
422 changed files with 361335 additions and 0 deletions
@@ -0,0 +1,70 @@
+**Language / Язык:** [English](seed-profiles.md) | [Русский](ru/seed-profiles.md)
+
+# Seed profiles
+
+Seeds replace the vSphere inventory **atomically** using deterministic MOIDs
+so labs are reproducible. Definitions live in
+[`app/vsphere/profiles.py`](../app/vsphere/profiles.py).
+
+```bash
+make seed                          # default: large (10 hosts / 1000 VMs)
+VSPHERE_PROFILE=small make seed
+```
+
+## Profiles
+
+| Profile | Contents |
+|---|---|
+| `small` | 3 ESXi hosts, 2 datastores, 2 networks, one datacenter/cluster/resource-pool, and five named VMs: `web-01`, `web-02`, `db-01`, `app-01`, `jumpbox` (mixed power states). Used by unit/integration tests. |
+| `large` (default) | Configurable hosts/VMs (`SEED_VSPHERE_LARGE_HOSTS` default 10, `SEED_VSPHERE_LARGE_VMS` default 1000), 4 datastores, 4 networks/portgroups, a `VmwareDistributedVirtualSwitch`, production/staging/templates VM folders. The first five VMs match the `small` names for cookbook stability; the rest are generated (`web-`, `app-`, `db-`, `cache-`, `batch-`, `jump-`, `ci-`, `mon-`, `log-`, `ml-` role prefixes). |
+| `demo-cluster` | `large` with 20 hosts / 1000 VMs — an enterprise-shaped dataset for UI demos. |
+
+Every profile also seeds the four lab credentials, role-scoped permissions
+(see [Authorization](domains/authz.md)), and — where the platform tables
+exist — a starter content library, tag categories/tags, and datastore file
+metadata (`seed_platform_extras`).
+
+## Examples
+
+```bash
+make seed                                   # large, 10 hosts / 1000 VMs
+VSPHERE_PROFILE=small make seed
+VSPHERE_PROFILE=demo-cluster make seed
+VSPHERE_PROFILE=large VSPHERE_HOSTS=20 VSPHERE_VMS=5000 make seed
+```
+
+Or run the seed CLI directly with the underlying environment variables (for
+example from a non-`make` script or CI step):
+
+```bash
+SEED_VSPHERE_PROFILE=small \
+  docker compose run --rm --entrypoint python simulator -m app.simulation.seed_cli
+```
+
+## Topology shape
+
+Every profile builds the same skeleton (`Datacenters` folder → `Datacenter` →
+host/vm/datastore/network sub-folders → one `ClusterComputeResource` +
+`ResourcePool`), then scales hosts, datastores, portgroups, and VMs. VM MOIDs
+are `vm-{100+n}`; host MOIDs are `host-{10+n}`; each VM carries the same
+hardware shape used by both REST (`hardware/*`) and SOAP (`VirtualMachineConfigInfo`)
+responses — NICs, disks, CD-ROM, boot order, and a synthetic guest IP/filesystem.
+
+## Demo cluster via UI
+
+The interactive console can load the demo dataset and reseed on demand:
+
+- `POST /ui/api/demo/load` — loads `demo-cluster`
+- `POST /ui/api/demo/unload` — wipes API-created state, then loads `small`
+- `GET /ui/api/demo/state`
+- `POST /ui/api/vsphere/seed?profile=small|large|demo-cluster` — reseed any profile
+
+These UI helper endpoints are development-oriented and are not separately
+authenticated today. Treat them as lab controls only.
+
+## Reseed vs client state
+
+Terraform, Pulumi, and Ansible may still hold resource state after a reseed
+(VM MOIDs and names can change). Refresh or destroy/recreate external state
+after replacing the PostgreSQL inventory. See [Operations](operations.md) and
+[Clients](clients.md).