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,96 @@
|
||||
**Language / Язык:** [English](configuration.md) | [Русский](ru/configuration.md)
|
||||
|
||||
# Configuration
|
||||
|
||||
Application settings are loaded from the environment (see `.env.example`).
|
||||
Docker Compose injects many of these for the `simulator` service; values
|
||||
declared under `environment:` in `docker-compose.yml` override `.env` for that
|
||||
service. The typed settings model lives in [`app/config.py`](../app/config.py).
|
||||
|
||||
## Core
|
||||
|
||||
| Variable | Default / example | Meaning |
|
||||
|---|---|---|
|
||||
| `APP_HOST` | `0.0.0.0` | Bind address |
|
||||
| `APP_PORT` | `8080` | Internal uvicorn listen port (not published; the gateway publishes vCenter HTTPS) |
|
||||
| `DATABASE_URL` | `postgresql://vmware:vmware@postgres:5432/vmware_simulator` | asyncpg DSN |
|
||||
| `DB_POOL_MIN_SIZE` | `1` | Pool minimum |
|
||||
| `DB_POOL_MAX_SIZE` | `10` | Pool maximum |
|
||||
| `DB_CONNECT_TIMEOUT_SECONDS` | `10` | Connect timeout |
|
||||
| `DB_COMMAND_TIMEOUT_SECONDS` | `30` | Command timeout |
|
||||
| `LOG_LEVEL` | `INFO` | Logging level |
|
||||
| `REQUEST_ID_HEADER` | `X-Request-ID` | Request correlation header |
|
||||
|
||||
## vSphere seed inventory
|
||||
|
||||
| Variable | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `SEED_VSPHERE_PROFILE` | `large` | `small` \| `large` \| `demo-cluster` — see [Seed profiles](seed-profiles.md) |
|
||||
| `SEED_VSPHERE_LARGE_HOSTS` | `10` | Host count for the `large` profile |
|
||||
| `SEED_VSPHERE_LARGE_VMS` | `1000` | VM count for the `large` profile |
|
||||
|
||||
## Optional legacy plane
|
||||
|
||||
| Variable | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `ENABLE_PVE_STUB` | `false` | Enables the legacy Proxmox VE `/api2/*` stub plane inherited from a shared platform lineage. Native vSphere `/api` + `/rest` + `/sdk` is the default and primary plane regardless of this flag. |
|
||||
|
||||
## Contract and catalog
|
||||
|
||||
| Variable | Meaning |
|
||||
|---|---|
|
||||
| `CONTRACT_SNAPSHOT` | Optional path to a normalized PVE-style snapshot (only relevant with `ENABLE_PVE_STUB=true`) |
|
||||
| `CONTRACT_FALLBACK` | `error` (default), `schema-default`, or `fixture` — fallback behaviour for the optional stub plane |
|
||||
| `COMPATIBILITY_EVIDENCE` | Optional evidence JSON path used by compatibility reports |
|
||||
| `CATALOG_ARTIFACT_URL_6` … `_9` | Labels backing the vSphere catalog majors (6→7.0, 7→7.0 U3, 8→8.0, 9→8.0 U2); stub URLs, not live downloads |
|
||||
|
||||
Runtime hot-swap (Web UI / `POST /ui/api/contract/apply?major=N`) switches the
|
||||
active **catalog** major used by the Web UI and compatibility/evidence
|
||||
reports. It does not gate the registered REST/SOAP surface — every known
|
||||
route is always served with its real handler or DB-backed stub. See
|
||||
[API versions](api-versions.md).
|
||||
|
||||
## Security and tasks
|
||||
|
||||
| Variable | Meaning |
|
||||
|---|---|
|
||||
| `TICKET_SIGNING_KEY` | HMAC signing key for sessions (**change outside toy labs**) |
|
||||
| `TASK_WORKER_CONCURRENCY` | Number of leased asyncio workers (1–32) |
|
||||
| `TASK_LEASE_SECONDS` | PostgreSQL task lease duration |
|
||||
| `SIMULATION_TIME_SCALE` | Accelerates simulated task durations (higher = faster) |
|
||||
|
||||
## Client test hooks
|
||||
|
||||
| Variable | Meaning |
|
||||
|---|---|
|
||||
| `TEST_DATABASE_URL` | Integration-test DSN |
|
||||
| `VSPHERE_BASE` | Target base URL used by cookbooks/probes (`https://localhost` from the host, `http://simulator:8080` from inside Compose) |
|
||||
|
||||
## Ports and TLS
|
||||
|
||||
| Endpoint | Use |
|
||||
|---|---|
|
||||
| `https://localhost` | Primary vCenter HTTPS entry (curl, browsers, pyvmomi, govmomi, Terraform, most examples) |
|
||||
| `http://localhost` | HTTP lab face |
|
||||
| `localhost:5434` | PostgreSQL (localhost only) |
|
||||
| Internal `simulator:8080` | Direct FastAPI process; only reachable inside the Compose network |
|
||||
|
||||
The checked-in certificate under `docker/tls/` is disposable development
|
||||
material. Never reuse it outside local labs. See [Security](security.md) and
|
||||
[Ports](ports.md).
|
||||
|
||||
## Compose notes
|
||||
|
||||
- `migrate` runs once; `simulator` waits for a successful migrate.
|
||||
- Development Compose bind-mounts the repository and enables Uvicorn reload.
|
||||
- The `api-gateway` (nginx) service publishes `443`/`80` and proxies to the
|
||||
internal `simulator:8080` process; it sets `X-VMware-Service` /
|
||||
`X-Forwarded-Port` so future routers can tell which listener was used.
|
||||
|
||||
## Open and unused example keys
|
||||
|
||||
`.env.example` still lists a few keys from the shared platform lineage that
|
||||
are **not** consumed by the current vSphere-first settings model, notably
|
||||
`SIMULATION_SEED`, `SIMULATOR_ADMIN_ENABLED`, and `SIMULATOR_ADMIN_TOKEN`. Do
|
||||
not assume an authenticated `/_simulator` admin API exists today — see
|
||||
[Security](security.md).
|
||||
Reference in New Issue
Block a user