Files

T

Sergey Antropoff 0773f721ea Align sized cluster seeds and GET dumps with PVE wire shapes; restyle DATA panel.

- Scale small/large/big seeds (3×50 / 10×1000 / 20×2000) with proportional
  backups, snapshots, HA, replication, Ceph capacity, and OSD totals
  (10 / 100 / 500) plus matching node disks and crush/pg metadata
- Enrich handler responses for apt, certificates, qemu/lxc status, storage,
  SDN, metrics export, and related cluster/node dumps
- Flatten nested body_example fields into PARAMS and sync the request body
  via dotted paths (oVirt-style)
- Restyle DATA controls as size cards with full-width Reset to minimal /
  Refresh stats; unload reloads the minimal cluster

2026-07-18 08:46:11 +03:00

7.4 KiB

Raw Permalink Blame History

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

Быстрый старт

Поднимите локальный лабораторный кластер, пройдите аутентификацию и выполните первый цикл чтения/мутации против симулятора.

Требования

Docker и Docker Compose
make (необязательно, но используется в документированных командах)

Python, линтеры и тесты запускаются внутри контейнеров. Для повседневной работы локальный Python-инструментарий не нужен.

Выберите путь

Путь	Когда использовать
Опубликованный образ	Самый быстрый старт с `inecs/proxmox-api-simulator`
Helm / Kubernetes	Установка в кластер с Ingress + Let's Encrypt
Checkout для разработки	Вклад в проект / bind-mount исходников / HTTPS-шлюз на `:8006`

1a. Опубликованный образ (Docker Hub)

Используется docker-compose.release.yml — PostgreSQL + runtime-симулятор из Hub + лабораторный HTTPS-шлюз. Нужен checkout с docker/tls/ (self-signed материалы). Сборка исходников не требуется.

Только лаборатория / CI — перед shared или сетевым демо смените TICKET_SIGNING_KEY и пароль БД. См. SECURITY.md.

# из этого репозитория (compose + docker/tls/)
docker compose -f docker-compose.release.yml pull
docker compose -f docker-compose.release.yml up -d
docker compose -f docker-compose.release.yml run --rm --entrypoint python \
  simulator -m app.simulation.seed_cli

Закрепите версию:

IMAGE_TAG=0.1.0 docker compose -f docker-compose.release.yml up -d

Make-цели (git checkout):

make release-up
make release-seed PROFILE=small

Порт хоста	Сервис
`8006`	HTTPS API + Web UI через лабораторный TLS-шлюз (как у реального PVE)
`5432`	PostgreSQL (только localhost)

Миграции выполняются автоматически через одноразовый сервис migrate.

Далее переходите к разделу Дождитесь готовности.

1b. Checkout для разработки

make install
make up

Сервисы:

Порт хоста	Сервис
`8006`	HTTPS API + Web UI через nginx TLS-шлюз (как у реального PVE)
`5432`	PostgreSQL (только localhost)

У реального Proxmox VE REST API доступен только как https://<host>:8006/api2/json/.... Лаборатория публикует то же: HTTPS на хосте :8006 через development TLS-шлюз; см. Порты и TLS. Хост :8007 не используется (на железе это обычно PBS, не API PVE).

Миграции применяются автоматически до того, как симулятор станет готов.

2. Дождитесь готовности

curl -sS http://localhost:8006/health/live
curl -sS http://localhost:8006/health/ready

/health/ready возвращает HTTP 503, пока PostgreSQL недоступен и не применена последняя упакованная миграция.

3. Загрузите профиль seed

make seed PROFILE=small

small создаёт узел pve01, две QEMU-гостевые ВМ (100, 101), один LXC (200), локальные хранилища и стандартных development-принципалов. Другие размеры — в Профилях seed.

4. Проверьте версию API

curl -sS http://localhost:8006/api2/json/version | jq .

При холодном старте контракт по умолчанию — встроенный снимок PVE 9.2.3 в Docker Compose. Переключайте мажорные версии 6–9 из Web UI или через Версии API.

5. Пройдите аутентификацию

curl -sk -X POST \
  -d 'username=root@pam&password=secret' \
  http://localhost:8006/api2/json/access/ticket | jq .

Сохраните ticket и CSRFPreventionToken из data. Для мутаций отправляйте:

Cookie: PVEAuthCookie=<ticket>
Header: CSRFPreventionToken: <token>

Подробнее: Аутентификация.

6. Получите список гостей и запустите одного

# замените TICKET / CSRF из предыдущего ответа
curl -sk -H "Cookie: PVEAuthCookie=$TICKET" \
  http://localhost:8006/api2/json/nodes/pve01/qemu | jq .

curl -sk -X POST \
  -H "Cookie: PVEAuthCookie=$TICKET" \
  -H "CSRFPreventionToken: $CSRF" \
  http://localhost:8006/api2/json/nodes/pve01/qemu/100/status/start | jq .

Асинхронные операции возвращают строку UPID. Опрашивайте, пока задача не завершится:

curl -s -H "Cookie: PVEAuthCookie=$TICKET" \
  "http://localhost:8006/api2/json/nodes/pve01/tasks/${UPID}/status" | jq .

7. Откройте Web UI

Перейдите на http://localhost:8006/ — интерактивная консоль, каталог контрактов (PVE 6–9), представление совместимости, применение runtime- контракта и управление demo-кластером. Скриншоты и полный список возможностей — в Web UI.

8. Попробуйте клиентскую библиотеку

# из корня репозитория после make up + seed
python examples/python/proxmoxer_cookbook.py

Другие стеки: Клиенты и examples/.

Готово, когда…

/health/ready возвращает {"status":"ok"} (или эквивалентное OK-тело)
/api2/json/version сообщает активную версию контракта
Вход по тикету для root@pam успешен
nodes/pve01/qemu перечисляет seeded ВМ
Хотя бы один путь power или create возвращает UPID, который успешно завершается

Дальнейшие шаги

Конфигурация — env vars, workers, путь к контракту
Версии API — горячая замена мажоров 6–9
Клиенты — Ansible, Terraform, Pulumi, Go, Java, Perl
Эксплуатация — reseed, migrate, обновления

7.4 KiB Raw Permalink Blame History Unescape Escape