Sergey Antropoff
48df10b17e
- Harden DB-backed handlers and seed profiles; align client wire shapes for cluster resources, QEMU config, and node SSL fields - Serve plain HTTP on Compose :8006; keep TLS optional (--profile tls) and terminate HTTPS at Kubernetes Ingress - Add pulumi-tests (full contract surface majors 6–9 + BPG lifecycle) and make pulumi-tests - Ship bilingual docs, CHANGELOG, SECURITY, CONTRIBUTING, and GitHub Actions (make ci + Compose/Helm validation)
80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
**Language / Язык:** [English](../api-versions.md) | [Русский](api-versions.md)
|
||
|
||
# Версии API (PVE 6–9)
|
||
|
||
Симулятор поставляет авторитетные импортированные контракты для четырёх мажорных
|
||
версий Proxmox VE. Покрытие реестра обработчиков **100% проверено** для каждой:
|
||
|
||
| Мажор | Исходная версия | Объявленных методов | Покрытие обработчиками |
|
||
|---|---|---:|---:|
|
||
| 6 | 6.4-15 | 504 | 100% |
|
||
| 7 | 7.4-16 | 540 | 100% |
|
||
| 8 | 8.4.5 | 605 | 100% |
|
||
| 9 | 9.2.3 | 675 | 100% |
|
||
|
||
Более старые мажорные версии переиспользуют текущие семантические обработчики плюс
|
||
синонимы путей, зарегистрированные в `app/handlers/legacy_aliases.py` (например,
|
||
исторические написания путей Ceph и backup).
|
||
|
||
## Холодный старт
|
||
|
||
Задайте `CONTRACT_SNAPSHOT` путь к нормализованному снимку. Docker Compose по
|
||
умолчанию закрепляет встроенную ревизию PVE **9.2.3**.
|
||
|
||
`GET /api2/json/version` возвращает поля, производные от `source_version` **активного**
|
||
снимка.
|
||
|
||
## Горячая замена (runtime)
|
||
|
||
Просмотрите любой мажор в каталоге Web UI, затем **Apply as runtime**, или вызовите:
|
||
|
||
```http
|
||
POST /ui/api/contract/apply?major=7
|
||
```
|
||
|
||
Эффекты:
|
||
|
||
- Маршруты `/api2/json` и `/api2/extjs` в памяти заменяются под блокировкой
|
||
приложения.
|
||
- `/version`, OpenAPI, метаданные реализации и состояние совместимости обновляются
|
||
для нового мажора.
|
||
- Изменение **локально для процесса** и **не сохраняется**.
|
||
- Перезапуск восстанавливает `CONTRACT_SNAPSHOT`.
|
||
|
||
Просмотр каталога (`GET /ui/api/catalog?major=N`) **сам по себе** не меняет
|
||
runtime; меняет только apply.
|
||
|
||
### Рекомендации для клиентов
|
||
|
||
- Явно закрепляйте мажор в CI (env холодного старта **или** apply + проверка
|
||
`/version` перед набором тестов).
|
||
- Горячая замена на лету может инвалидировать предположения клиента о схемах и
|
||
путях — избегайте во время длинных прогонов Terraform/Ansible, если прогон не
|
||
владеет переключением.
|
||
- После apply перепроверьте `/admin/compatibility` для активного runtime.
|
||
|
||
## Режимы fallback
|
||
|
||
`CONTRACT_FALLBACK` управляет поведением для необъявленных обработчиков:
|
||
|
||
| Значение | Поведение |
|
||
|---|---|
|
||
| `error` (по умолчанию) | HTTP 501 с явным сообщением в стиле pending-handler |
|
||
| `schema-default` | Синтез возвращаемого значения из схемы контракта |
|
||
| `fixture` | Только fixture-данные, встроенные в контракт метода |
|
||
|
||
При полном покрытии обработчиков активного контракта объявленные методы не должны
|
||
попадать в fallback. Оставляйте `error`, чтобы регрессии оставались видимыми.
|
||
|
||
## Evidence vs реестр
|
||
|
||
**Покрытие реестра** означает, что у каждого объявленного метода зарегистрирован
|
||
семантический обработчик (нет систематического 501 для этого контракта).
|
||
|
||
**Verified** в смысле этого проекта — мажорные версии прогоняются через наборы
|
||
совместимости и автоматизацию на наличие обработчиков для 6–9. Многомерный evidence
|
||
JSON может со временем расширяться для более глубоких edge-case заявлений;
|
||
предпочитайте живой `/admin/compatibility`, когда процесс запущен.
|
||
|
||
См. [Совместимость](compatibility.md).
|