- 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
39 lines
3.7 KiB
Markdown
39 lines
3.7 KiB
Markdown
# 📋 Отчет по задаче: 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].
|