Prepare 0.1.0 for lab release: durable handlers, HTTP Compose, CI, and pulumi-tests.

- Harden DB-backed handlers and seed profiles; align client wire shapes for cluster resources, QEMU config, and node SSL fields - Serve plain HTTP on Compose :8006; keep TLS optional (--profile tls) and terminate HTTPS at Kubernetes Ingress - Add pulumi-tests (full contract surface majors 6–9 + BPG lifecycle) and make pulumi-tests - Ship bilingual docs, CHANGELOG, SECURITY, CONTRIBUTING, and GitHub Actions (make ci + Compose/Helm validation)
2026-07-18 04:18:05 +03:00
parent 777926487b
commit 48df10b17e
172 changed files with 7528 additions and 1208 deletions
@@ -0,0 +1,157 @@
+**Language / Язык:** [English](../operations.md) | [Русский](operations.md)
+
+# Эксплуатация
+
+## Команды day-2
+
+```bash
+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 PROFILE=small # atomic reseed
+make shell              # interactive tools container
+```
+
+## Миграции
+
+Упорядоченные SQL-файлы применяются транзакционно и записывают SHA-256
+checksum. Повторный запуск `make db-migrate` безопасен. Изменение уже
+применённой миграции отклоняется. `/health/ready` остаётся недоступным, пока
+не применена последняя упакованная миграция. Воркеры задач повторяют захват
+после того, как миграции догонят актуальное состояние.
+
+## Reseed
+
+```bash
+make seed PROFILE=medium
+```
+
+Reseed заменяет изменяемое состояние симуляции. Внешнее состояние автоматизации
+(Terraform state files, Pulumi stacks, Ansible inventories с закодированными
+VMID) может после этого рассинхронизироваться — обновите или пересоздайте эти
+боковые каналы.
+
+## Восстановление воркеров
+
+Воркеры используют аренды PostgreSQL. После сбоя или перезапуска просроченные
+аренды перехватываются, а незавершённая работа может безопасно продолжиться.
+Настраиваемые параметры: `TASK_WORKER_CONCURRENCY`, `TASK_LEASE_SECONDS`,
+`SIMULATION_TIME_SCALE`.
+
+## Смена API major по умолчанию
+
+1. Предпочтительно задайте `CONTRACT_SNAPSHOT` на нужный bundled/normalized
+   snapshot для холодного старта (Compose / k8s / OpenShift).
+2. Используйте Web UI apply или `POST /ui/api/contract/apply?major=N` для
+   временных переключений в пределах процесса.
+
+## Резервное копирование состояния лаборатории
+
+PostgreSQL — система записи. Используйте обычное резервное копирование и
+восстановление Postgres (pg_dump / снимки томов), если нужно сохранить
+засеянную лабораторию. Контейнеры приложения одноразовые, пока сохранён том БД.
+
+## Публикация в Docker Hub
+
+`make release` собирает **runtime**-образ (production target — не локальный
+bind-mounted образ `dev`) и публикует его в Docker Hub:
+
+```bash
+docker login   # once; account must own or can push to DOCKERHUB_USER
+make release
+```
+
+Значения по умолчанию:
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `DOCKERHUB_USER` | `inecs` | Namespace/org в Docker Hub |
+| `IMAGE_NAME` | `proxmox-api-simulator` | Имя репозитория |
+| `VERSION` | from `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   # build/tag locally without pushing
+```
+
+Опубликованные теги:
+
+- `inecs/proxmox-api-simulator:<version>`
+- `inecs/proxmox-api-simulator:latest` (если не `PUSH_LATEST=0`)
+
+После публикации при необходимости вставьте
+[обзор Docker Hub](../docker-hub-overview.md) в описание репозитория Hub и
+держите GitHub About в одном стиле («stateful Proxmox VE API simulator», а не
+тонкий mock).
+
+CI в GitHub Actions на каждый push/PR в `main` запускает `make ci` и проверку
+Compose/Helm (см. `.github/workflows/ci.yml`).
+
+## Быстрый старт с опубликованным compose-файлом
+
+[`docker-compose.release.yml`](../../docker-compose.release.yml) подтягивает
+runtime-образ из Hub и запускает PostgreSQL + migrate + simulator:
+
+```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 http://localhost:8006/health/ready
+open http://localhost:8006/
+```
+
+Вспомогательные команды из git checkout:
+
+```bash
+make release-up
+make release-seed PROFILE=small
+make release-down
+```
+
+Полезные переопределения:
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `DOCKER_IMAGE` | `inecs/proxmox-api-simulator` | Репозиторий образа |
+| `IMAGE_TAG` | `latest` | Тег для pull |
+| `SIMULATOR_PORT` | `8006` | HTTPS-порт на хосте (TLS-шлюз) |
+| `TICKET_SIGNING_KEY` | lab default | Меняйте вне игрушечных лаб |
+| `POSTGRES_PASSWORD` | `proxmox` | Пароль БД |
+
+Development и release Compose публикуют **HTTPS `:8006`** на хосте через nginx
+TLS-шлюз (тот же порт, что у реального PVE). Процесс симулятора остаётся HTTP
+на `:8006` внутри Docker-сети. См.
+[Порты и TLS](configuration.md#порты-и-tls).
+
+Для Kubernetes с публичным TLS (cert-manager / Let's Encrypt) используйте Helm
+chart — см. [Kubernetes / Helm](kubernetes.md).
+
+## Обновления
+
+1. Подтяните / пересоберите образы (`make install` / `make docker-build` по
+   необходимости).
+2. Выполните миграции.
+3. Подтвердите `/health/ready`.
+4. Повторно проверьте `/admin/compatibility` и `/api2/json/version`.
+5. Повторно запустите `make test-compatibility`, если в CI проверяете внешних
+   клиентов (засеивает профиль **medium** — `pve1`/`pve2`/`pve3` — для migration
+   smoke).
+
+## Сброс лаборатории
+
+```bash
+make seed PROFILE=small
+# or via UI: unload demo → minimal, then seed again
+```
+
+Для жёсткого сброса БД используйте `make db-reset` (разрушительно — см. help
+Makefile).