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,166 @@
+**Language / Язык:** [English](../kubernetes.md) | [Русский](kubernetes.md)
+
+# Kubernetes / Helm
+
+Разверните опубликованный образ runtime из Docker Hub с помощью чарта
+[`helm/vmware-api-simulator`](../../helm/vmware-api-simulator).
+
+Образ: [`inecs/vmware-api-simulator`](https://hub.docker.com/r/inecs/vmware-api-simulator)
+
+## Требования
+
+- Kubernetes 1.27+ (или сопоставимая версия)
+- Helm 3.14+
+- [Ingress NGINX](https://kubernetes.github.io/ingress-nginx/) (или другой
+  IngressClass с поддержкой HTTP-01)
+- [cert-manager](https://cert-manager.io/), установленный на весь кластер
+
+Пример установки cert-manager:
+
+```bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.2/cert-manager.yaml
+```
+
+## Быстрая установка (Hub-релиз + Ingress + Let's Encrypt)
+
+Из git checkout этого репозитория:
+
+```bash
+helm upgrade --install vmware-sim ./helm/vmware-api-simulator \
+  -n vmware-sim --create-namespace \
+  -f ./helm/vmware-api-simulator/values-ingress-example.yaml \
+  --set certManager.email=you@example.com \
+  --set ingress.hosts[0].host=vmware-sim.example.com \
+  --set ingress.tls[0].hosts[0]=vmware-sim.example.com \
+  --set secret.ticketSigningKey="$(openssl rand -hex 32)" \
+  --set postgresql.auth.password="$(openssl rand -hex 16)"
+```
+
+Что это делает:
+
+1. Скачивает `inecs/vmware-api-simulator:0.1.0` (см. `image.tag` в примерном файле).
+2. Устанавливает встроенный PostgreSQL 17 (`postgres:17.5-bookworm`, как и в Compose).
+3. Выполняет миграции схемы в init-контейнере (идемпотентно).
+4. Загружает лабораторный профиль `small` (`seed.enabled=true`).
+5. Создаёт ресурсы `ClusterIssuer`:
+   - `letsencrypt-prod`
+   - `letsencrypt-staging`
+6. Создаёт Ingress с
+   `cert-manager.io/cluster-issuer: letsencrypt-prod` и TLS-секретом
+   `vmware-api-simulator-tls`.
+
+DNS для `vmware-sim.example.com` должен указывать на ваш Ingress-контроллер.
+Затем:
+
+```bash
+kubectl -n vmware-sim get certificate,ingress,pods
+# дождитесь Certificate READY=True
+curl -sS https://vmware-sim.example.com/health/ready
+open https://vmware-sim.example.com/
+```
+
+Seeded-логин по умолчанию: `administrator@vsphere.local` / `VMware1!`.
+
+### Сначала staging (рекомендуется)
+
+Проверьте HTTP-01, не расходуя лимиты запросов production:
+
+```bash
+helm upgrade --install vmware-sim ./helm/vmware-api-simulator \
+  -n vmware-sim --create-namespace \
+  -f ./helm/vmware-api-simulator/values-ingress-example.yaml \
+  --set certManager.email=you@example.com \
+  --set certManager.useStaging=true \
+  --set ingress.hosts[0].host=vmware-sim.example.com \
+  --set ingress.tls[0].hosts[0]=vmware-sim.example.com \
+  --set secret.ticketSigningKey="$(openssl rand -hex 32)"
+```
+
+Браузеры не будут доверять staging CA — используйте `curl -k` во время
+тестирования. Переключите `certManager.useStaging=false` и пересоздайте
+Certificate/TLS-секрет для production.
+
+## Минимальная установка (ClusterIP + port-forward)
+
+```bash
+helm upgrade --install vmware-sim ./helm/vmware-api-simulator \
+  -n vmware-sim --create-namespace \
+  --set secret.ticketSigningKey="$(openssl rand -hex 32)" \
+  --set seed.enabled=true
+
+kubectl -n vmware-sim port-forward svc/vmware-sim-vmware-api-simulator 8080:8080
+```
+
+Откройте http://127.0.0.1:8080/. Service выставляет внутренний порт
+приложения (`8080`, см. [Порты](ports.md)) — чарт не запускает TLS-gateway
+nginx, используемый Compose; в production выставляйте TLS перед сервисом
+через Ingress, либо обращайтесь к обычному HTTP-сервису для локального
+тестирования.
+
+## Внешний PostgreSQL
+
+```bash
+helm upgrade --install vmware-sim ./helm/vmware-api-simulator \
+  -n vmware-sim --create-namespace \
+  --set postgresql.enabled=false \
+  --set secret.ticketSigningKey="$(openssl rand -hex 32)" \
+  --set secret.databaseUrl='postgresql://user:pass@pg.example.com:5432/vmware_simulator'
+```
+
+Либо используйте `secret.existingSecret` с ключами `DATABASE_URL` и
+`TICKET_SIGNING_KEY`.
+
+## Как работает выпуск TLS
+
+Когда `certManager.enabled=true` и `certManager.createClusterIssuer=true`,
+чарт создаёт объекты ACME `ClusterIssuer`, которые решают HTTP-01 через ваш
+Ingress-класс. Шаблон Ingress добавляет:
+
+```yaml
+metadata:
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  tls:
+    - secretName: vmware-api-simulator-tls
+      hosts: [vmware-sim.example.com]
+```
+
+Затем cert-manager создаёт `Certificate`, проходит HTTP-01 и сохраняет пару
+ключей Let's Encrypt в этом TLS-секрете. Чарт **не** устанавливает
+cert-manager или Ingress-контроллер — только issuer'ы и связку с Ingress.
+
+Если ClusterIssuer'ы уже существуют на уровне кластера, задайте:
+
+```yaml
+certManager:
+  enabled: true
+  createClusterIssuer: false
+  issuerName: your-existing-issuer
+```
+
+## Эксплуатация
+
+```bash
+# логи
+kubectl -n vmware-sim logs -l app.kubernetes.io/instance=vmware-sim -c simulator -f
+
+# reseed
+kubectl -n vmware-sim exec deploy/vmware-sim-vmware-api-simulator -- \
+  python -m app.simulation.seed_cli
+# SEED_VSPHERE_PROFILE через: kubectl set env ... либо --set seed.profile=demo-cluster и upgrade
+
+# удаление
+helm -n vmware-sim uninstall vmware-sim
+```
+
+## Справочник по values
+
+См. [`helm/vmware-api-simulator/values.yaml`](../../helm/vmware-api-simulator/values.yaml)
+и [README чарта](../../helm/vmware-api-simulator/README.ru.md). Связанная
+документация:
+
+- [Быстрый старт](getting-started.md) — пути через Compose
+- [Эксплуатация](operations.md) — публикация в Docker Hub / release compose
+- [Безопасность](security.md) — лабораторные учётные данные и граница доверия
+- [Порты](ports.md) — внутренний `8080` в сравнении с опубликованными портами gateway