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,151 @@
+**Language / Язык:** [English](../operations.md) | [Русский](operations.md)
+
+# Эксплуатация
+
+## Команды day-2
+
+```bash
+make up                 # запуск стека
+make down               # остановка стека
+make restart
+make logs
+make dev                # foreground-workflow, ориентированный на reload
+make db-migrate         # идемпотентные миграции
+make seed               # атомарный reseed (SEED_VSPHERE_PROFILE=large по умолчанию)
+make shell              # интерактивный контейнер с инструментами
+```
+
+## Миграции
+
+Упорядоченные SQL-файлы применяются транзакционно и записывают контрольные
+суммы SHA-256. Повторный запуск `make db-migrate` безопасен. Изменение уже
+применённой миграции отклоняется. `/health/ready` остаётся недоступным, пока
+не появится последняя упакованная миграция.
+
+## Reseed
+
+```bash
+make seed                        # large (по умолчанию)
+VSPHERE_PROFILE=small make seed
+VSPHERE_PROFILE=demo-cluster make seed
+```
+
+Reseed атомарно заменяет инвентарь в PostgreSQL. Состояние внешней
+автоматизации (файлы состояния Terraform, стеки Pulumi, инвентари Ansible,
+кодирующие MOID/имена ВМ) может после этого разойтись — обновите или
+пересоздайте эти внешние каналы. См. [Профили seed](seed-profiles.md).
+
+## Восстановление workers
+
+CIS task workers используют аренды PostgreSQL (`FOR UPDATE SKIP LOCKED`).
+После сбоя или перезапуска просроченные аренды переиспользуются, и
+незавершённая работа безопасно возобновляется. Настраиваемые параметры:
+`TASK_WORKER_CONCURRENCY`, `TASK_LEASE_SECONDS`, `SIMULATION_TIME_SCALE`.
+
+## Изменение мажора каталога по умолчанию
+
+1. Мажор каталога по умолчанию — **9** (поверхность 8.0 U2 / Automation 9.1)
+   при холодном старте; это не ограничивает таблицу маршрутов runtime (см.
+   [Версии API](api-versions.md)).
+2. Используйте «Apply as runtime» в Web UI или
+   `POST /ui/api/contract/apply?major=N`, чтобы переключить мажор каталога
+   локально для процесса, для целей просмотра/evidence.
+
+## Резервное копирование состояния лаборатории
+
+PostgreSQL — это система записи (system of record). Используйте обычные
+backup/restore для Postgres (`pg_dump` / снимки томов), если нужно сохранить
+seeded-лабораторию. Контейнеры приложения одноразовые, пока сохраняется том
+базы данных.
+
+## Публикация в Docker Hub
+
+`make release` собирает образ **runtime** (build target `runtime`, а не
+локальный bind-mounted образ `dev`) и публикует его в Docker Hub:
+
+```bash
+docker login   # один раз; учётная запись должна владеть или иметь права push в DOCKERHUB_USER
+make release
+```
+
+Значения по умолчанию:
+
+| Переменная | По умолчанию | Значение |
+|---|---|---|
+| `DOCKERHUB_USER` | `inecs` | Namespace/организация Docker Hub |
+| `IMAGE_NAME` | `vmware-api-simulator` | Имя репозитория |
+| `VERSION` | из `pyproject.toml` | Тег образа |
+| `PUSH_LATEST` | `1` | Также помечать/публиковать `:latest` |
+
+Примеры:
+
+```bash
+make release
+make release VERSION=0.2.0
+make release DOCKERHUB_USER=myorg PUSH_LATEST=0
+make release-build   # локальная сборка/тегирование без публикации
+```
+
+Опубликованные теги:
+
+- `inecs/vmware-api-simulator:<version>`
+- `inecs/vmware-api-simulator:latest` (если не задано `PUSH_LATEST=0`)
+
+## Быстрый старт с опубликованным compose-файлом
+
+[`docker-compose.release.yml`](../../docker-compose.release.yml) скачивает
+runtime-образ из Hub и запускает PostgreSQL + migrate + симулятор + HTTPS
+gateway:
+
+```bash
+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/
+```
+
+Вспомогательные команды из git checkout:
+
+```bash
+make release-up
+make release-seed PROFILE=small
+make release-down
+```
+
+Полезные переопределения:
+
+| Переменная | По умолчанию | Значение |
+|---|---|---|
+| `DOCKER_IMAGE` | `inecs/vmware-api-simulator` | Репозиторий образа |
+| `IMAGE_TAG` | `latest` | Тег для скачивания |
+| `HTTP_PORT` | `80` | Порт хоста для HTTP |
+| `HTTPS_PORT` | `443` | Порт хоста для HTTPS |
+| `POSTGRES_PORT` | `127.0.0.1:5434` | Bind хоста для Postgres |
+| `TICKET_SIGNING_KEY` | лабораторное значение по умолчанию | Меняйте вне игрушечных лабораторий |
+| `POSTGRES_PASSWORD` | `vmware` | Пароль БД |
+
+Для Kubernetes с публичным TLS (cert-manager / Let's Encrypt) используйте
+Helm-чарт — см. [Kubernetes / Helm](kubernetes.md).
+
+## Обновления
+
+1. Скачайте / пересоберите образы (`make install` / `make docker-build` по
+   ситуации).
+2. Выполните миграции (`make db-migrate`).
+3. Убедитесь, что `/health/ready` отвечает нормально.
+4. Перепроверьте `/ui/api/compatibility?major=9` и
+   `/api/appliance/system/version`.
+5. При необходимости заново запустите `make test-vsphere` /
+   `make vsphere-matrix`, если проверяете поверхность после обновления.
+
+## Сброс лаборатории
+
+```bash
+make seed PROFILE=small
+# или через UI: unload demo → small, затем снова seed
+```
+
+Для жёсткого сброса базы данных используйте `make db-reset` (деструктивно —
+см. справку Makefile).