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)
180 lines
7.4 KiB
Markdown
180 lines
7.4 KiB
Markdown
**Language / Язык:** [English](../getting-started.md) | [Русский](getting-started.md)
|
||
|
||
# Быстрый старт
|
||
|
||
Поднимите локальный лабораторный кластер, пройдите аутентификацию и выполните первый
|
||
цикл чтения/мутации против симулятора.
|
||
|
||
## Требования
|
||
|
||
- Docker и Docker Compose
|
||
- `make` (необязательно, но используется в документированных командах)
|
||
|
||
Python, линтеры и тесты запускаются **внутри** контейнеров. Для повседневной работы
|
||
локальный Python-инструментарий не нужен.
|
||
|
||
## Выберите путь
|
||
|
||
| Путь | Когда использовать |
|
||
|---|---|
|
||
| [Опубликованный образ](#1a-опубликованный-образ-docker-hub) | Самый быстрый старт с `inecs/proxmox-api-simulator` |
|
||
| [Helm / Kubernetes](kubernetes.md) | Установка в кластер с Ingress + Let's Encrypt |
|
||
| [Checkout для разработки](#1b-checkout-для-разработки) | Вклад в проект / bind-mount исходников / HTTPS-шлюз на `:8006` |
|
||
|
||
## 1a. Опубликованный образ (Docker Hub)
|
||
|
||
Используется [`docker-compose.release.yml`](../../docker-compose.release.yml) —
|
||
PostgreSQL + runtime-симулятор из Hub + лабораторный HTTPS-шлюз. Нужен checkout
|
||
с `docker/tls/` (self-signed материалы). Сборка исходников не требуется.
|
||
|
||
> Только лаборатория / CI — перед shared или сетевым демо смените
|
||
> `TICKET_SIGNING_KEY` и пароль БД. См. [SECURITY.md](../../SECURITY.md).
|
||
|
||
```bash
|
||
# из этого репозитория (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
|
||
```
|
||
|
||
Закрепите версию:
|
||
|
||
```bash
|
||
IMAGE_TAG=0.1.0 docker compose -f docker-compose.release.yml up -d
|
||
```
|
||
|
||
Make-цели (git checkout):
|
||
|
||
```bash
|
||
make release-up
|
||
make release-seed PROFILE=small
|
||
```
|
||
|
||
| Порт хоста | Сервис |
|
||
|---|---|
|
||
| `8006` | HTTPS API + Web UI через лабораторный TLS-шлюз (как у реального PVE) |
|
||
| `5432` | PostgreSQL (только localhost) |
|
||
|
||
Миграции выполняются автоматически через одноразовый сервис `migrate`.
|
||
|
||
Далее переходите к разделу [Дождитесь готовности](#2-дождитесь-готовности).
|
||
|
||
## 1b. Checkout для разработки
|
||
|
||
```bash
|
||
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](configuration.md#порты-и-tls). Хост **`:8007` не используется**
|
||
(на железе это обычно PBS, не API PVE).
|
||
|
||
Миграции применяются автоматически до того, как симулятор станет готов.
|
||
|
||
## 2. Дождитесь готовности
|
||
|
||
```bash
|
||
curl -sS http://localhost:8006/health/live
|
||
curl -sS http://localhost:8006/health/ready
|
||
```
|
||
|
||
`/health/ready` возвращает HTTP 503, пока PostgreSQL недоступен **и** не применена
|
||
последняя упакованная миграция.
|
||
|
||
## 3. Загрузите профиль seed
|
||
|
||
```bash
|
||
make seed PROFILE=small
|
||
```
|
||
|
||
`small` создаёт узел `pve01`, две QEMU-гостевые ВМ (`100`, `101`), один LXC (`200`),
|
||
локальные хранилища и стандартных development-принципалов. Другие размеры — в
|
||
[Профилях seed](seed-profiles.md).
|
||
|
||
## 4. Проверьте версию API
|
||
|
||
```bash
|
||
curl -sS http://localhost:8006/api2/json/version | jq .
|
||
```
|
||
|
||
При холодном старте контракт по умолчанию — встроенный снимок PVE **9.2.3** в Docker
|
||
Compose. Переключайте мажорные версии 6–9 из Web UI или через
|
||
[Версии API](api-versions.md).
|
||
|
||
## 5. Пройдите аутентификацию
|
||
|
||
```bash
|
||
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>`
|
||
|
||
Подробнее: [Аутентификация](authentication.md).
|
||
|
||
## 6. Получите список гостей и запустите одного
|
||
|
||
```bash
|
||
# замените 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. Опрашивайте, пока задача не завершится:
|
||
|
||
```bash
|
||
curl -s -H "Cookie: PVEAuthCookie=$TICKET" \
|
||
"http://localhost:8006/api2/json/nodes/pve01/tasks/${UPID}/status" | jq .
|
||
```
|
||
|
||
## 7. Откройте Web UI
|
||
|
||
Перейдите на [http://localhost:8006/](http://localhost:8006/) — интерактивная
|
||
консоль, каталог контрактов (PVE 6–9), представление совместимости, применение runtime-
|
||
контракта и управление demo-кластером. Скриншоты светлой/тёмной темы и полный список
|
||
возможностей — в [Web UI](web-ui.md).
|
||
|
||
## 8. Попробуйте клиентскую библиотеку
|
||
|
||
```bash
|
||
# из корня репозитория после make up + seed
|
||
python examples/python/proxmoxer_cookbook.py
|
||
```
|
||
|
||
Другие стеки: [Клиенты](clients.md) и [`examples/`](../../examples/README.ru.md).
|
||
|
||
## Готово, когда…
|
||
|
||
- `/health/ready` возвращает `{"status":"ok"}` (или эквивалентное OK-тело)
|
||
- `/api2/json/version` сообщает активную версию контракта
|
||
- Вход по тикету для `root@pam` успешен
|
||
- `nodes/pve01/qemu` перечисляет seeded ВМ
|
||
- Хотя бы один путь power или create возвращает UPID, который успешно завершается
|
||
|
||
## Дальнейшие шаги
|
||
|
||
- [Конфигурация](configuration.md) — env vars, workers, путь к контракту
|
||
- [Версии API](api-versions.md) — горячая замена мажоров 6–9
|
||
- [Клиенты](clients.md) — Ansible, Terraform, Pulumi, Go, Java, Perl
|
||
- [Эксплуатация](operations.md) — reseed, migrate, обновления
|