vmware-api-simulator/README.ru.md

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

vmware-api-simulator

Stateful-асинхронный симулятор API VMware vSphere для тестирования 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 (~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-отчётов. См. Совместимость, compatibility 0.1.0 и Покрытие API.

Это измеримое покрытие route-registry и обработчиков лабораторного симулятора — не утверждение, что каждый краевой случай vSphere или поведение ESXi-железа воспроизводится идентично продакшен-vCenter.

Быстрый старт (опубликованный образ)

Образ: inecs/vmware-api-simulator

Нужен git checkout этого репозитория (Compose монтирует docker/gateway/ и docker/tls/ рядом с compose-файлом).

Docker Compose

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)

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.

• Lab UI + REST (Compose gateway): https://localhost/
• Схема FastAPI: https://localhost/docs
• Админ по умолчанию после seed: administrator@vsphere.local / VMware1!

Быстрый старт (разработка из репозитория)

Сборка и запуск development-стека с bind-mount из этого репозитория:

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

Web UI

Интерактивная консоль со светлой/тёмной темой, каталог эндпоинтов для vSphere majors 6–9, редактирование request/response и runtime contract hot-swap.

Полный обзор и дополнительные скриншоты: Web UI.

Учётные данные (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. Индекс: docs/README.md · docs/ru/README.md.

Руководство	Описание
Быстрый старт	Первая успешная лабораторная сессия
Конфигурация	Переменные окружения и Compose
Аутентификация	Сессии, vmware-api-session-id, привилегии
Версии API	Catalog majors 6–9 и hot-swap
Поверхность API	Маршрутизация REST/SOAP, coverage registry, stubs
Покрытие API	Broadcom universe vs реализованная поверхность
Клиенты и примеры	Python, Go, Java, Perl, Ansible, Terraform, Pulumi
Профили seed	Детерминированные фикстуры инвентаря
Домены	Session, inventory, VM, storage, networking, tagging, SOAP, tasks, …
Web UI	Интерактивная консоль и каталоги
Эксплуатация	Reseed, migrate, release, upgrade
Kubernetes / Helm	Образ Hub + Ingress + Let's Encrypt
Безопасность	Модель угроз лаборатории и учётные данные
Наблюдаемость	Эндпоинты health и логирование
Порты	Опубликованные порты хоста и внутренние сервисы
Устранение неполадок	Типичные сбои
FAQ	Краткие ответы
Архитектура	Границы компонентов
Совместимость	Модель evidence и матрица релизов

Исполняемые cookbook'и находятся в examples/. Lab-набор на официальном pulumi-vsphere (проверки непустых export'ов, HTML-отчёт) — в pulumi-tests/; запуск: 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.

Python (requests) через HTTPS gateway

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-цели

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; см. Эксплуатация):

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.
• Удалённые IdP / LDAP / live NSX / live ACME directories симулируются локально; они не обращаются к реальным внешним системам.
• Опциональная legacy Proxmox VE stub-плоскость доступна за ENABLE_PVE_STUB (выключена по умолчанию) из общей platform lineage; это не основная поверхность проекта.

Лицензия

Apache-2.0 — см. LICENSE.

Руководство по Web UI: docs/ru/web-ui.md.