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,23 @@
+**Language / Язык:** [English](../../examples/ansible.md) | [Русский](ansible.md)
+
+# Ansible
+
+Playbook использует модуль `uri` против HTTPS-шлюза
+(`https://localhost`): вход по Basic-auth сессии, затем вызовы с
+заголовком `vmware-api-session-id` для остального жизненного цикла.
+
+```bash
+cd examples/ansible
+ansible-playbook -i inventory.ini vsphere_playbook.yml
+```
+
+[`vsphere_playbook.yml`](../../../examples/ansible/vsphere_playbook.yml) охватывает:
+вход в сессию, список ВМ, создание, power on, опрос CIS-задачи
+(`/api/cis/tasks/{task}`), запись файла в лабораторную гостевую виртуальную ФС,
+power off, удаление и выход из сессии.
+
+Перед опорой на фиксированные имена ВМ/MOID из предыдущего запуска выполните
+повторный seed симулятора (`make seed`).
+
+Для lab-набора на официальном `pulumi-vsphere` (непустые export'ы, HTML-отчёт)
+см. [`pulumi-tests/`](../../../pulumi-tests/README.ru.md) или `make pulumi-tests`.
@@ -0,0 +1,21 @@
+**Language / Язык:** [English](../../examples/go.md) | [Русский](go.md)
+
+# Go
+
+Использует стандартную библиотеку Go (`net/http`) против
+`https://localhost` с Basic-auth сессией
+(`vmware-api-session-id`).
+
+```bash
+cd examples/go
+go run .
+```
+
+Переопределите значения по умолчанию через `VSPHERE_BASE`, `VSPHERE_USER`,
+`VSPHERE_PASSWORD`, `VSPHERE_VM_NAME`. См. [`main.go`](../../../examples/go/main.go)
+для потока session → list → create → power → wait-task → delete и вспомогательной
+функции `waitTask`, которая опрашивает `GET /api/cis/tasks/{task}`.
+
+Проверка TLS отключена в HTTP-клиенте только для локального самоподписанного
+сертификата разработческого шлюза — не переиспользуйте такой transport против
+реального vCenter.
@@ -0,0 +1,22 @@
+**Language / Язык:** [English](../../examples/java.md) | [Русский](java.md)
+
+# Java
+
+Cookbook на Java 11+ `HttpClient` с Basic-auth сессией
+(`vmware-api-session-id`) против `https://localhost`. Без сторонних
+JSON-библиотек — ответы разбираются простым строковым извлечением полей,
+достаточным для лабораторного smoke.
+
+```bash
+cd examples/java
+javac Cookbook.java && java Cookbook
+```
+
+Переопределите значения по умолчанию переменными окружения `VSPHERE_BASE`,
+`VSPHERE_USER`, `VSPHERE_PASSWORD`, `VSPHERE_VM_NAME`. См.
+[`Cookbook.java`](../../../examples/java/Cookbook.java) для потока session →
+create → power → wait-task → delete.
+
+Клиент устанавливает trust-all `SSLContext` только для локального
+самоподписанного сертификата разработческого шлюза — не переиспользуйте его
+против реального vCenter.
@@ -0,0 +1,53 @@
+**Language / Язык:** [English](../../examples/overview.md) | [Русский](overview.md)
+
+# Обзор примеров клиентов
+
+## Чеклист запуска
+
+```bash
+make up
+curl -skf https://localhost/health/ready
+make seed
+curl -sk https://localhost/api/appliance/system/version
+```
+
+## Конечные точки
+
+| URL | Когда использовать |
+|---|---|
+| `https://localhost` | curl, pyvmomi, govmomi, Terraform, Pulumi, Ansible, Go, Java, Perl — всё из `examples/` |
+| `http://localhost` | Лабораторный HTTP без TLS (без рукопожатия TLS) |
+
+## Краткая справка по аутентификации
+
+**Сессия (REST)**
+
+```bash
+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
+```
+
+**SOAP Login**
+
+```bash
+python examples/python/vsphere_soap_smoke.py https://localhost
+```
+
+## Ожидание задач
+
+Не считайте HTTP-ответ мутации достаточным признаком «ВМ запущена». Вызовы
+power, clone, relocate, snapshot и OVF-deploy возвращают `{ "task": "task-…" }`;
+опрашивайте `GET /api/cis/tasks/{task}`, пока `status` не станет `SUCCEEDED` или
+`FAILED`. См. [Задачи](../domains/tasks.md).
+
+## Предупреждение о повторном seed
+
+`make seed` заменяет инвентарь PostgreSQL. После этого обновите состояние
+Terraform/Pulumi/Ansible — см. [Профили seed](../seed-profiles.md).
+
+## Дерево исполняемых примеров
+
+См. [`examples/README.ru.md`](../../../examples/README.ru.md). Lab-набор на
+официальном `pulumi-vsphere` — в
+[`pulumi-tests/`](../../../pulumi-tests/README.ru.md) (`make pulumi-tests`).
@@ -0,0 +1,20 @@
+**Language / Язык:** [English](../../examples/perl.md) | [Русский](perl.md)
+
+# Perl
+
+Cookbook на `HTTP::Tiny` + `JSON` с Basic-auth сессией
+(`vmware-api-session-id`) против `https://localhost`.
+
+```bash
+cd examples/perl
+cpanm --installdeps .   # или установите HTTP::Tiny, JSON, IO::Socket::SSL вручную
+perl cookbook.pl
+```
+
+Переопределите значения по умолчанию переменными окружения `VSPHERE_BASE`,
+`VSPHERE_USER`, `VSPHERE_PASSWORD`, `VSPHERE_VM_NAME`. См.
+[`cookbook.pl`](../../../examples/perl/cookbook.pl) для потока session → list →
+create → power → wait-task → delete.
+
+`HTTP::Tiny` создаётся с `verify_SSL => 0` только для локального самоподписанного
+сертификата разработческого шлюза.
@@ -0,0 +1,32 @@
+**Language / Язык:** [English](../../examples/pulumi.md) | [Русский](pulumi.md)
+
+# Pulumi
+
+[`examples/pulumi/`](../../../examples/pulumi/) — Python-программа Pulumi на
+официальном [`pulumi-vsphere`](https://www.pulumi.com/registry/packages/vsphere/)
+(SOAP/VIM) против симулятора — тот же путь провайдера, что у Terraform
+`hashicorp/vsphere`.
+
+```bash
+cd examples/pulumi
+pip install -r requirements.txt
+pulumi plugin install resource vsphere 4.17.0
+pulumi stack init dev   # один раз
+pulumi config set server localhost
+pulumi config set --secret password 'VMware1!'
+pulumi up
+```
+
+Конфигурация (`pulumi config set`): `server` (по умолчанию `localhost`), `user`
+(по умолчанию `administrator@vsphere.local`), `password` (secret), `datacenter`,
+`datastore`, `cluster`, `network`, `vm_name` (по умолчанию `pulumi-lab-01`).
+
+Та же осторожность при reseed, что и для Terraform: состояние PostgreSQL
+симулятора и state Pulumi независимы. Закрепите major каталога для
+воспроизводимого CI, если ваш workflow зависит от вывода Web UI/evidence (см.
+[Версии API](../api-versions.md)) — сами runtime-маршруты доступны всегда
+независимо от major.
+
+Для lab-набора (inventory + folder + VM + tags, проверки непустых export'ов,
+HTML-отчёт) см. [`pulumi-tests/`](../../../pulumi-tests/README.ru.md) или
+`make pulumi-tests` из корня репозитория.
@@ -0,0 +1,33 @@
+**Language / Язык:** [English](../../examples/python-requests.md) | [Русский](python-requests.md)
+
+# Python — REST (requests / stdlib)
+
+Сырой HTTP к REST-шлюзу vSphere без vendor SDK.
+
+```bash
+pip install -r examples/python/requirements.txt
+python examples/python/requests_cookbook.py
+```
+
+[`requests_cookbook.py`](../../../examples/python/requests_cookbook.py)
+демонстрирует общий поток session → create → wait-for-task → power on → wait →
+power off → delete с помощью `requests`; идентификатор сессии передаётся в
+заголовке `vmware-api-session-id`.
+
+Для варианта без внешних зависимостей, только на стандартной библиотеке
+(`urllib`), см. [`vsphere_rest_smoke.py`](../../../examples/python/vsphere_rest_smoke.py):
+
+```bash
+python examples/python/vsphere_rest_smoke.py https://localhost
+```
+
+Для комбинированного smoke REST-create + SOAP-`CreateVM_Task` + guest-filesystem
+см. [`vsphere_lifecycle.py`](../../../examples/python/vsphere_lifecycle.py):
+
+```bash
+VSPHERE_BASE=https://localhost python examples/python/vsphere_lifecycle.py
+```
+
+Все три скрипта по умолчанию используют `administrator@vsphere.local` / `VMware1!`
+и отключают проверку TLS только для локального самоподписанного сертификата
+разработческого шлюза.
@@ -0,0 +1,32 @@
+**Language / Язык:** [English](../../examples/terraform.md) | [Русский](terraform.md)
+
+# Terraform
+
+[`examples/terraform/vsphere/`](../../../examples/terraform/vsphere/) использует
+официальный провайдер `hashicorp/vsphere` (SOAP `/sdk` под капотом), направленный
+на локальный HTTPS-шлюз (`https://localhost`) с
+`allow_unverified_ssl = true` для разработческого сертификата.
+
+```bash
+cd examples/terraform/vsphere
+terraform init
+TF_VAR_create_lab_vm=false terraform plan   # только data sources (datacenter/cluster/datastore/network/VM)
+TF_VAR_create_lab_vm=true terraform apply   # также создаёт лабораторную ВМ (SOAP CreateVM_Task)
+```
+
+Значения по умолчанию (`variables.tf`): `vsphere_server = "localhost"`,
+`vsphere_user = "administrator@vsphere.local"`,
+`vsphere_password = "VMware1!"`, `datacenter = "Datacenter"`,
+`cluster = "Cluster"`, `datastore = "datastore1"`,
+`network = "VM Network"`, `vm_name = "web-01"` (ВМ из seed `small`/`large`).
+
+Версии плагинов провайдера меняются быстро — закрепите версии в блоке
+`required_providers` под то, что вы протестировали. После `make seed` обновите
+или пересоздайте state, чтобы допущения об именах ВМ/MOID оставались согласованными.
+
+Этот cookbook — отправная точка для лабораторного CI, а не сертификация каждого
+resource/data source `hashicorp/vsphere` против полного реестра маршрутов. См.
+[SOAP / VIM](../domains/soap.md) для точных операций, лежащих в основе create/read
+путей провайдера, и
+[`pulumi-tests/`](../../../pulumi-tests/README.ru.md) для lab-набора
+`pulumi-vsphere` (`make pulumi-tests`).
@@ -0,0 +1,15 @@
+**Language / Язык:** [English](../../examples/troubleshooting-clients.md) | [Русский](troubleshooting-clients.md)
+
+# Устранение неполадок клиентов
+
+| Симптом | Решение |
+|---|---|
+| Ошибки TLS-сертификата | Используйте `:443` с `verify=False` / `insecure`/`allow_unverified_ssl=true` **только** локально или plain HTTP `:80` |
+| 401 на первом вызове | Отправляйте `Authorization: Basic …` только на `/api/session` (или SOAP `Login`); все остальные вызовы требуют `vmware-api-session-id` |
+| 403 на power/create | Возможно, вы используете `readonly@vsphere.local` — переключитесь на `administrator@vsphere.local` или `operator@vsphere.local` |
+| ВМ не найдена | Имена ВМ seed `small`: `web-01`, `web-02`, `db-01`, `app-01`, `jumpbox` — не числовые VMID в стиле Proxmox |
+| Create возвращает MOID, а не task | REST `POST /api/vcenter/vm` синхронно возвращает MOID новой ВМ; только **power/clone/relocate/snapshot/OVF-deploy** возвращают `{ "task": "…" }` |
+| Create провайдера vs task | Опрашивайте `/api/cis/tasks/{task}`; многие провайдеры (Terraform, Pulumi) уже ждут внутри — сырые HTTP/Go/Java/Perl клиенты часто забывают |
+| Drift после reseed | Обновите/пересоздайте state Terraform/Pulumi/Ansible после `make seed` |
+| Сессия истекла во время выполнения | Сессии имеют скользящий TTL 2 часа; выполните повторный login, если длинный скрипт простаивал дольше |
+| SOAP `Login` не проходит | Убедитесь, что envelope направлен на `/sdk` с `SOAPAction` (пустая строка допустима) и `Content-Type: text/xml` |