Files
buryan-infra/ops/F2-3-REMEDIATION-API-REPORT.md
root 72c48ded12 docs: add F2-3 Remediation API post-mortem and audit report
- Documented architecture, artifacts, and success metrics
- Noted LXC+Docker cgroup locking behavior for future fix (Variant B)
- Formalized the completion of the secure agent control channel
2026-10-07 20:14:52 +03:00

3.7 KiB

📋 Отчет по задаче: F2-3 Remediation API & Agent Control

Статус: ✅ DONE
Дата завершения: 2026-10-07
Ответственный: Admin-Buryans (Roman)

1. Цель задачи

Создать безопасный, контролируемый канал для выполнения административных действий (перезапуск сервисов) через Telegram-бота без предоставления прямого root-доступа агентам.

2. Реализованная архитектура

  1. Telegram Bot (comms-agent): Принимает команду от администратора, проверяет права (is_admin), формирует JSON-запрос.
  2. Remediation API (FastAPI на PVE, порт 5000):
    • Принимает запросы только с валидным X-API-Key.
    • Строгий allowlist действий (пока реализовано только restart_service).
    • Динамически читает карту сервисов из services_map.json.
  3. Proxmox VE (Hyperwisor): Выполняет команды pct от имени root, возвращая реальный статус операции.

3. Ключевые артефакты

Артефакт Путь Описание
api.py /opt/remediation-api/api.py Ядро API на FastAPI с валидацией и выполнением команд.
services_map.json /opt/remediation-api/services_map.json Динамическая карта соответствия "Имя сервиса → ID контейнера".
discover_services.sh /opt/remediation-api/discover_services.sh Скрипт автообнаружения сервисов (Service Discovery).
bot.py services/comms/telegram-admin-bot/bot.py Обновленный код бота с поддержкой Inline-кнопок и динамических запросов.
Runbooks services/*/runbook.md 29 автоматически сгенерированных runbook'ов для всех сервисов.

4. Метрики успеха

  • ✅ Полностью исключен хардкод ID контейнеров в коде бота.
  • ✅ Успешная сквозная проверка: Telegram → Bot → API → Proxmox → Выполнение команды.
  • ✅ Реализована ролевая модель (только ADMIN_ID может нажимать кнопки).

5. Известные особенности и ограничения (To-Do для Варианта Б)

  • Нюанс LXC + Docker: При попытке выполнить pct stop или pct reboot на контейнерах, внутри которых запущен Docker (например, CT 155 Matrix, CT 118 Radarr), Proxmox может вернуть ошибку unable to get PID. Это связано с тем, что демоны Docker/containerd удерживают блокировки cgroups.
  • План решения: Заменить жесткий pct stop/start на мягкий перезапуск через pct exec <vmid> -- systemctl reboot или корректную остановку Docker-демона перед остановкой контейнера.

6. Следующие шаги

  1. Вариант Б: Исправление механизма перезапуска для LXC с Docker внутри.
  2. F2-5: [Уточнить из Master Plan, например: Расширение возможностей агентов / Интеграция с Observability].