REST API AlertWeb

Control plane API для автоматизации панели. За nginx браузер и скрипты ходят на префикс /api; бэкенд видит пути без префикса (/vms, не /api/vms).

Введение

# Базовый URL (через nginx)
export API=https://panel.example.ru/api
export TOKEN=<access_token>

• Формат: JSON, UTF-8
• Авторизация: Authorization: Bearer <access_token> (кроме login/health)
• OpenAPI: GET $API/openapi.yaml на вашей установке
• Permissions: RBAC — каждый endpoint требует scope (см. роли в панели)

Аутентификация

curl -sS -X POST "$API/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.ru","password":"your-password"}'

{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG...",
  "expires_in": 3600
}

curl -sS -X POST "$API/auth/refresh" \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token":"'"$REFRESH"'"}'

curl -sS "$API/auth/me" -H "Authorization: Bearer $TOKEN"

Дашборд и аудит

curl -sS "$API/dashboard/stats" -H "Authorization: Bearer $TOKEN"

Пользователи и RBAC

curl -sS "$API/users" -H "Authorization: Bearer $TOKEN"
curl -sS -X POST "$API/users" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"email":"ops@example.ru","password":"...","first_name":"Ops","role_ids":[2]}'

Инфраструктура

Локации, кластеры, ноды

# Создать ноду
curl -sS -X POST "$API/nodes" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "node-msk-01",
    "cluster_id": 1,
    "address": "10.0.0.11",
    "ssh_port": 22
  }'
# Ответ содержит bootstrap_token для agent.env

Виртуальные машины

curl -sS -X POST "$API/vms" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "web-prod-01",
    "cluster_id": 1,
    "template_id": 3,
    "vcpu": 4,
    "ram_mb": 8192,
    "disk_gb": 40,
    "ip_pool_id": 1,
    "root_password": "ChangeMe123!",
    "ssh_public_key": "ssh-ed25519 AAAA..."
  }'

curl -sS -X POST "$API/vms/$VM_UUID/actions/start" \
  -H "Authorization: Bearer $TOKEN"

curl -sS -X POST "$API/vms/$VM_UUID/console" \
  -H "Authorization: Bearer $TOKEN"

IPAM

curl -sS -X POST "$API/ipam/pools" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "public-ipv4",
    "cidr": "203.0.113.0/24",
    "gateway": "203.0.113.1",
    "dns_servers": ["8.8.8.8","1.1.1.1"]
  }'

Шаблоны ОС

ISO-образы

curl -sS -X POST "$API/iso/upload" -H "Authorization: Bearer $TOKEN" \
  -F "name=debian-12" -F "os_type=linux" -F "file=@debian.iso"

Фоновые задачи (jobs)

curl -sS "$API/jobs/$JOB_UUID/logs" -H "Authorization: Bearer $TOKEN"

Миграции

Webhooks

curl -sS -X POST "$API/webhooks" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "slack-migrations",
    "url": "https://hooks.example.com/alertweb",
    "events": ["migration.completed", "migration.failed"],
    "secret": "whsec_..."
  }'

Firewall

Marketplace

API-ключи

Ключи вида alertweb_* с ограничением scopes — альтернатива JWT для автоматизации.

curl -sS -X POST "$API/api-keys" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"terraform","scopes":["vms.read","vms.write","nodes.read"]}'

curl -sS "$API/vms" -H "Authorization: Bearer alertweb_xxxx..."

Платформа и лицензия

Ошибки и коды

• 401 — невалидный или просроченный token
• 403 — нет permission (RBAC)
• 404 — объект не найден
• 409 — конфликт состояния (VM busy, нода drained)
• 422 — валидация тела запроса

{
  "error": "permission denied",
  "code": "forbidden"
}