Files

T

inecs f8d3cbdd59 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

5.6 KiB

Raw Permalink Blame History

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

Поверхность API

Путь запроса

Middleware назначает или пересылает ID запроса (REQUEST_ID_HEADER).
FastAPI направляет запрос в роутер vSphere REST (/api, /rest), роутер SOAP (/sdk) или (если ENABLE_PVE_STUB=true) в опциональный legacy-стаб.
/api/session (либо /rest/com/vmware/cis/session, либо SOAP Login) определяет принципала и выдаёт vmware-api-session-id.
Зависимости require_read / require_privilege(...) проверяют роли сессии перед раскрытием или мутацией ресурсов.
Глубокий обработчик (базовая логика инвентаря/жизненного цикла/тегов/ контента/appliance) или DB-backed поверхность стабов выполняется против состояния, хранимого в PostgreSQL.
Долгие операции (power, clone, relocate, snapshot, деплой OVF) создают долговечную CIS-задачу и возвращают { "task": "task-…" }.

Две REST-поверхности в одном реестре

Core (глубокие) обработчики — ~104 комбинации verb+path в app/vsphere/rest/router.py, vm_ext.py, inventory_ext.py, platform_rest.py, tagging_rest.py, content_rest.py, appliance_ext.py, nfc_rest.py, tasks.py. Они читают и мутируют напрямую seeded-таблицы инвентаря/тегов/контента/ appliance.
DB-backed поверхность стабов — app/vsphere/rest/stub_surface.py отвечает на оставшиеся маршруты индекса операций Broadcom Automation API (зарегистрированные из universe.json) против vsphere_api_state. GET возвращает живые payload'ы, производные от инвентаря, когда это возможно, иначе — seeded-строки; PUT/PATCH сохраняются в vsphere_api_state; POST добавляет строки коллекции; DELETE их удаляет. Маркер "stub": true не возвращается — зонды видят реальные seeded-payload'ы.

Обе поверхности используют одну таблицу маршрутов; core-обработчики имеют приоритет над записями стабов, зарегистрированными для того же verb+path.

Legacy `/rest`

app/vsphere/rest/legacy.py оборачивает чтения vm/host/datastore/network/datacenter/cluster/power/appliance (и power ВМ) в конверты { "value": … } для более старых клиентов com.vmware.vcenter.*.

Ошибки (`app/vsphere/errors.py`)

Статус	`error_type`	Типичная причина
400	`invalid_argument` / `already_exists`	Некорректное тело, дублирующееся имя
401	`unauthenticated`	Отсутствующая/недействительная/истёкшая сессия
403	`unauthorized`	У сессии нет требуемой привилегии
404	`not_found`	Неизвестный параметр MOID/path
409	(зависит от обработчика)	Недопустимый переход состояния питания, конфликт блокировки
501	`error`	Достижимо только через fallback опционального legacy-стаба для необъявленных методов

Все тела ошибок следуют форме vSphere Automation: { "error_type": "...", "messages": [{ "default_message": "...", "id": "...", "args": [] }] }.

Задачи

Асинхронная работа (power, clone, snapshot, relocate, деплой OVF, guest customize) возвращает id задачи. Опрашивайте:

GET /api/cis/tasks/{task}

Строки задач фиксируются в vsphere_tasks; progress равен 100, как только status становится SUCCEEDED/FAILED. HTTP 200/201 на запросе мутации означает «принято», а не «ВМ уже в конечном состоянии». См. Задачи.

Исследование

Интерактивная документация FastAPI: /docs
Инспектор методов в Web UI: / → каталог → метод
Вспомогательные API UI: /ui/api/catalog, /ui/api/method, /ui/api/compatibility
Реестр покрытия: app/vsphere/rest/coverage.py
Матрица уровней пути / каталога: app/vsphere/contracts/matrix.py

Эндпоинты совместимости

Path	Формат
`/ui/api/compatibility?major=N`	JSON

См. Совместимость и Покрытие API для полной разбивки Broadcom-universe в сравнении с реализованным.

5.6 KiB Raw Permalink Blame History