vmware-api-simulator/docs/operations.md

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

Operations

Day-2 commands

make up                 # start stack
make down               # stop stack
make restart
make logs
make dev                # foreground reload-oriented workflow
make db-migrate         # idempotent migrations
make seed               # atomic reseed (SEED_VSPHERE_PROFILE=large by default)
make shell              # interactive tools container

Migrations

Ordered SQL files apply transactionally and record SHA-256 checksums. Re-running make db-migrate is safe. Altering an already-applied migration is rejected. /health/ready stays unavailable until the latest packaged migration is present.

Reseed

make seed                        # large (default)
VSPHERE_PROFILE=small make seed
VSPHERE_PROFILE=demo-cluster make seed

Reseed replaces the PostgreSQL inventory atomically. External automation state (Terraform state files, Pulumi stacks, Ansible inventories that encode VM MOIDs/names) may then drift — refresh or recreate those side channels. See Seed profiles.

Worker recovery

CIS task workers use PostgreSQL leases (FOR UPDATE SKIP LOCKED). After a crash or restart, expired leases are reclaimed and incomplete work can resume safely. Tunables: TASK_WORKER_CONCURRENCY, TASK_LEASE_SECONDS, SIMULATION_TIME_SCALE.

Changing the default catalog major

1. The default catalog major is 9 (8.0 U2 / Automation 9.1 surface) at cold start; this does not gate the runtime route table (see API versions).
2. Use the Web UI "Apply as runtime" or POST /ui/api/contract/apply?major=N to switch the catalog major process-locally for browse/evidence purposes.

Backing up lab state

PostgreSQL is the system of record. Use normal Postgres backup/restore (pg_dump / volume snapshots) if you need to preserve a seeded laboratory. Application containers are disposable when the database volume remains.

Publishing to Docker Hub

make release builds the runtime image (the runtime build target — not the local bind-mounted dev image) and pushes it to Docker Hub:

docker login   # once; account must own or can push to DOCKERHUB_USER
make release

Defaults:

Variable	Default	Meaning
DOCKERHUB_USER	inecs	Docker Hub namespace/org
IMAGE_NAME	vmware-api-simulator	Repository name
VERSION	from pyproject.toml	Image tag
PUSH_LATEST	1	Also tag/push :latest

Examples:

make release
make release VERSION=0.2.0
make release DOCKERHUB_USER=myorg PUSH_LATEST=0
make release-build   # build/tag locally without pushing

Published tags:

• inecs/vmware-api-simulator:<version>
• inecs/vmware-api-simulator:latest (unless PUSH_LATEST=0)

Quick start with the published compose file

docker-compose.release.yml pulls the Hub runtime image and starts PostgreSQL + migrate + simulator + the HTTPS gateway:

docker compose -f docker-compose.release.yml up -d
docker compose -f docker-compose.release.yml run --rm --entrypoint python \
  simulator -m app.simulation.seed_cli

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

Helpers from a git checkout:

make release-up
make release-seed PROFILE=small
make release-down

Useful overrides:

Variable	Default	Meaning
DOCKER_IMAGE	inecs/vmware-api-simulator	Image repository
IMAGE_TAG	latest	Tag to pull
HTTP_PORT	80	Host HTTP port
HTTPS_PORT	443	Host HTTPS port
POSTGRES_PORT	127.0.0.1:5434	Host Postgres bind
TICKET_SIGNING_KEY	lab default	Change outside toy labs
POSTGRES_PASSWORD	vmware	DB password

For Kubernetes with public TLS (cert-manager / Let's Encrypt), use the Helm chart — see Kubernetes / Helm.

Upgrades

1. Pull / rebuild images (make install / make docker-build as appropriate).
2. Run migrations (make db-migrate).
3. Confirm /health/ready.
4. Re-check /ui/api/compatibility?major=9 and /api/appliance/system/version.
5. Re-run make test-vsphere / make vsphere-matrix / make pulumi-tests if you validate the surface after upgrading. Latest recorded lab numbers: Compatibility — Latest lab run.

Resetting a lab

make seed PROFILE=small
# or via UI: unload demo → small, then seed again

For a hard database reset use make db-reset (destructive — see Makefile help).