inecs
131e2e63d2
Record offline 161 passed, green test-vsphere probes, and full pulumi-tests 7/7 with REST matrix 1987/1987 (critical=0); note the Terraform cookbook binary mismatch separately.
236 lines
12 KiB
Markdown
236 lines
12 KiB
Markdown
**Language / Язык:** [English](README.md) | [Русский](README.ru.md)
|
||
|
||
# vmware-api-simulator
|
||
|
||
Stateful-асинхронный симулятор API [VMware vSphere](https://www.vmware.com/products/vsphere.html)
|
||
для тестирования API-клиентов и инфраструктурных инструментов без реального
|
||
кластера ESXi/vCenter.
|
||
|
||
Симулятор работает на PostgreSQL и предоставляет нативные поверхности vCenter:
|
||
**REST** Automation API (`/api`, legacy `/rest`) и **SOAP** VIM/PBM (`/sdk`).
|
||
Семантические обработчики сохраняют инвентарь, сессии, задачи, теги, content library
|
||
и права доступа; операции power/clone/relocate/snapshot выполняются как устойчивые
|
||
CIS-задачи с реальными id задач.
|
||
|
||
## Проверенное покрытие API
|
||
|
||
Покрытие отслеживается относительно публичного
|
||
[vSphere Automation API operations index](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/operation-index/)
|
||
(~1037 уникальных маршрутов verb+path в registry симулятора).
|
||
|
||
**Два слоя (прочитайте до таблицы):**
|
||
|
||
| Слой | Доля (major 9) | Смысл |
|
||
|---|---:|---|
|
||
| Core deep handlers | ~104 маршрута (~10%) | Инвентарь, lifecycle ВМ, tasks, tagging, content library, appliance, authz — реальная семантика в PostgreSQL |
|
||
| DB-backed stub surface | остальной registry (~90%) | Засеянный non-empty JSON по остальной таблице Broadcom (lab stand-in, не production parity) |
|
||
|
||
| Catalog major | Метка vSphere | Catalog floor / universe | Floor coverage |
|
||
|---|---|---:|---:|
|
||
| 6 | 7.0 | 31 / 1077 | 2.9% |
|
||
| 7 | 7.0 U3 | 77 / 1077 | 7.2% |
|
||
| 8 | 8.0 | 103 / 1077 | 9.6% |
|
||
| 9 | 8.0 U2 (Automation 9.1 surface) | **1077 / 1077** | **100% route registry** |
|
||
|
||
На major 9 обслуживается **полный route registry** (нет известных path 501):
|
||
deep handlers плюс stubs. Hot-swap (`POST /ui/api/contract/apply?major=N`)
|
||
меняет только **catalog** major для Web UI / evidence-отчётов. См.
|
||
[Совместимость](docs/ru/compatibility.md),
|
||
[compatibility 0.1.0](docs/ru/compatibility-0.1.0.md) и
|
||
[Покрытие API](docs/ru/api-coverage.md).
|
||
|
||
> Это измеримое покрытие route-registry и обработчиков лабораторного симулятора —
|
||
> не утверждение, что каждый краевой случай vSphere или поведение ESXi-железа
|
||
> воспроизводится идентично продакшен-vCenter.
|
||
|
||
## Быстрый старт (опубликованный образ)
|
||
|
||
Образ: [`inecs/vmware-api-simulator`](https://hub.docker.com/r/inecs/vmware-api-simulator)
|
||
|
||
Нужен git checkout этого репозитория (Compose монтирует `docker/gateway/` и
|
||
`docker/tls/` рядом с compose-файлом).
|
||
|
||
### Docker Compose
|
||
|
||
```bash
|
||
docker compose -f docker-compose.release.yml up -d --wait
|
||
# seed выполняется автоматически; при очистке БД:
|
||
# docker compose -f docker-compose.release.yml run --rm --entrypoint python \
|
||
# simulator -m app.simulation.seed_cli
|
||
|
||
curl -sk https://localhost/health/ready
|
||
SID=$(curl -sk -u 'administrator@vsphere.local:VMware1!' -X POST \
|
||
https://localhost/api/session | tr -d '"')
|
||
curl -sk -H "vmware-api-session-id: $SID" https://localhost/api/vcenter/vm
|
||
```
|
||
|
||
Или: `make release-up` (seed входит в release-стек)
|
||
|
||
### Helm (Kubernetes + Ingress + Let's Encrypt)
|
||
|
||
```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)"
|
||
```
|
||
|
||
Нужны Ingress-контроллер и cert-manager. Подробности:
|
||
[Kubernetes / Helm](docs/ru/kubernetes.md).
|
||
|
||
- Lab UI + REST (Compose gateway): [https://localhost/](https://localhost/)
|
||
- Схема FastAPI: [https://localhost/docs](https://localhost/docs)
|
||
- Админ по умолчанию после seed: `administrator@vsphere.local` / `VMware1!`
|
||
|
||
## Быстрый старт (разработка из репозитория)
|
||
|
||
Сборка и запуск development-стека с bind-mount из этого репозитория:
|
||
|
||
```bash
|
||
make install
|
||
make up
|
||
make seed PROFILE=small
|
||
|
||
curl -sk https://localhost/health/ready
|
||
curl -sk https://localhost/api/appliance/system/version
|
||
```
|
||
|
||
- HTTPS gateway (основная точка входа vCenter): `https://localhost`
|
||
- HTTP lab face: `http://localhost`
|
||
- PostgreSQL (только localhost): `5434`
|
||
- Внутренний процесс FastAPI (не публикуется на хост): `8080`
|
||
- Вшитый `docker/tls/server.key` — **только для лаборатории** localhost-сертификат;
|
||
не используйте его вне локального Compose.
|
||
- Схема FastAPI: [https://localhost/docs](https://localhost/docs)
|
||
|
||
### Web UI
|
||
|
||
Интерактивная консоль со светлой/тёмной темой, каталог эндпоинтов для vSphere
|
||
majors 6–9, редактирование request/response и runtime contract hot-swap.
|
||
|
||
|
||
|
||
Полный обзор и дополнительные скриншоты: [Web UI](docs/ru/web-ui.md).
|
||
|
||
## Учётные данные (seed)
|
||
|
||
Пароль `VMware1!` для всех засеянных principals:
|
||
|
||
| User | Role |
|
||
|---|---|
|
||
| `administrator@vsphere.local` | Administrator |
|
||
| `readonly@vsphere.local` | ReadOnly |
|
||
| `operator@vsphere.local` | VirtualMachinePowerUser |
|
||
| `vmadmin@vsphere.local` | VirtualMachineAdministrator |
|
||
|
||
## Документация
|
||
|
||
Документация двуязычная. Используйте переключатель **Language / Язык** в начале
|
||
каждой страницы или откройте русский корень [README.ru.md](README.ru.md). Индекс:
|
||
[docs/README.md](docs/README.md) · [docs/ru/README.md](docs/ru/README.md).
|
||
|
||
| Руководство | Описание |
|
||
|---|---|
|
||
| [Быстрый старт](docs/ru/getting-started.md) | Первая успешная лабораторная сессия |
|
||
| [Конфигурация](docs/ru/configuration.md) | Переменные окружения и Compose |
|
||
| [Аутентификация](docs/ru/authentication.md) | Сессии, `vmware-api-session-id`, привилегии |
|
||
| [Версии API](docs/ru/api-versions.md) | Catalog majors 6–9 и hot-swap |
|
||
| [Поверхность API](docs/ru/api-surface.md) | Маршрутизация REST/SOAP, coverage registry, stubs |
|
||
| [Покрытие API](docs/ru/api-coverage.md) | Broadcom universe vs реализованная поверхность |
|
||
| [Клиенты и примеры](docs/ru/clients.md) | Python, Go, Java, Perl, Ansible, Terraform, Pulumi |
|
||
| [Профили seed](docs/ru/seed-profiles.md) | Детерминированные фикстуры инвентаря |
|
||
| [Домены](docs/ru/domains/README.md) | Session, inventory, VM, storage, networking, tagging, SOAP, tasks, … |
|
||
| [Web UI](docs/ru/web-ui.md) | Интерактивная консоль и каталоги |
|
||
| [Эксплуатация](docs/ru/operations.md) | Reseed, migrate, release, upgrade |
|
||
| [Kubernetes / Helm](docs/ru/kubernetes.md) | Образ Hub + Ingress + Let's Encrypt |
|
||
| [Безопасность](docs/ru/security.md) | Модель угроз лаборатории и учётные данные |
|
||
| [Наблюдаемость](docs/ru/observability.md) | Эндпоинты health и логирование |
|
||
| [Порты](docs/ru/ports.md) | Опубликованные порты хоста и внутренние сервисы |
|
||
| [Устранение неполадок](docs/ru/troubleshooting.md) | Типичные сбои |
|
||
| [FAQ](docs/ru/faq.md) | Краткие ответы |
|
||
| [Архитектура](docs/ru/architecture.md) | Границы компонентов |
|
||
| [Совместимость](docs/ru/compatibility.md) | Модель evidence и матрица релизов |
|
||
|
||
Исполняемые cookbook'и находятся в [`examples/`](examples/README.ru.md). Lab-набор
|
||
на официальном [`pulumi-vsphere`](https://www.pulumi.com/registry/packages/vsphere/)
|
||
(проверки непустых export'ов, HTML-отчёт) — в
|
||
[`pulumi-tests/`](pulumi-tests/README.ru.md); запуск: `make pulumi-tests`.
|
||
|
||
Последний lab-прогон (**2026-07-18**): offline **161 passed**; probes
|
||
`test-vsphere` зелёные; полный `pulumi-tests` **7/7**, REST-матрица
|
||
**1987/1987** (`critical=0`). См.
|
||
[pulumi-tests/README.ru.md](pulumi-tests/README.ru.md#последний-lab-прогон-2026-07-18).
|
||
|
||
## Python (requests) через HTTPS gateway
|
||
|
||
```python
|
||
import requests
|
||
|
||
requests.packages.urllib3.disable_warnings()
|
||
session = requests.post(
|
||
"https://localhost/api/session",
|
||
auth=("administrator@vsphere.local", "VMware1!"),
|
||
verify=False, # local self-signed development certificate only
|
||
)
|
||
headers = {"vmware-api-session-id": session.json()}
|
||
vms = requests.get("https://localhost/api/vcenter/vm", headers=headers, verify=False)
|
||
print(vms.json())
|
||
```
|
||
|
||
SOAP / VIM клиенты (pyvmomi, govmomi, Terraform provider `hashicorp/vsphere`,
|
||
Pulumi) указывают на `https://localhost/sdk` с теми же учётными данными.
|
||
|
||
## Основные Make-цели
|
||
|
||
```bash
|
||
make up / make down / make logs / make dev
|
||
make seed # large vSphere seed (10 hosts / 1000 VMs)
|
||
VSPHERE_PROFILE=small make seed # compact inventory (3 hosts / 5 VMs)
|
||
make test # unit + contract (offline)
|
||
make test-vsphere # native vSphere unit + integration + surface + matrix
|
||
make vsphere-surface # probe REST coverage registry against the running gateway
|
||
make vsphere-matrix # full REST matrix: all verbs × majors 6-9 (no 5xx)
|
||
make evidence # regenerate evidence/vsphere-*.json ledgers
|
||
make db-migrate
|
||
make shell
|
||
make ci # ruff + mypy + offline pytest + surface probe
|
||
make release # build + push runtime image to Docker Hub
|
||
make release-up # pull/start docker-compose.release.yml
|
||
make release-seed PROFILE=small
|
||
```
|
||
|
||
Docker Hub release (нужен `docker login` как владелец Hub; см.
|
||
[Эксплуатация](docs/ru/operations.md)):
|
||
|
||
```bash
|
||
make release # inecs/vmware-api-simulator:<pyproject version> + :latest
|
||
make release VERSION=0.2.0 # override tag
|
||
make release-build # build/tag only, no push
|
||
make release-up && make release-seed # run the published stack locally
|
||
```
|
||
|
||
## Чем это не является
|
||
|
||
- Не гипервизор: нет выполнения ESXi/KVM на bare metal или nested hosts.
|
||
- Не drop-in multi-tenant production vCenter replacement.
|
||
- Нет Supervisor/Tanzu control plane, NSX Manager, deep vSAN, SAML/OIDC federation,
|
||
VECS certificate store — для некоторых из них есть lab-shaped stand-ins
|
||
(засеянные, non-binary-compatible данные). Handshake HttpNfcLease /
|
||
content-library transfer реализован на `/nfc` и связанных REST/SOAP-путях,
|
||
но не production-binary-compatible NFC uploads; см.
|
||
[docs/ru/api-coverage.md](docs/ru/api-coverage.md).
|
||
- Удалённые IdP / LDAP / live NSX / live ACME directories симулируются локально;
|
||
они не обращаются к реальным внешним системам.
|
||
- Опциональная legacy Proxmox VE stub-плоскость доступна за `ENABLE_PVE_STUB`
|
||
(**выключена** по умолчанию) из общей platform lineage; это не основная
|
||
поверхность проекта.
|
||
|
||
## Лицензия
|
||
|
||
Apache-2.0 — см. [LICENSE](LICENSE).
|
||
|
||
Руководство по Web UI: [docs/ru/web-ui.md](docs/ru/web-ui.md).
|