Введение

Настоящий документ содержит руководство по эксплуатации программного продукта EDA (Enhanced Dynamic Activation) — виртуального сетевого элемента с движком динамической активации сервисов. Документ предназначен для администраторов и операторов, осуществляющих повседневное управление, мониторинг и обслуживание программного обеспечения.

Эксплуатация включает совокупность процессов и процедур, направленных на обеспечение непрерывного и корректного функционирования EDA. В документе рассматриваются вопросы запуска и останова программы, мониторинга состояния, управления конфигурацией, сбора диагностической информации, а также типовые операции.

Целевая аудитория

Администраторы, осуществляющие управление экземплярами EDA

Операторы, выполняющие мониторинг и контроль работоспособности

Инженеры, участвующие в настройке и оптимизации параметров работы

Специалисты технической поддержки

Необходимая квалификация

Уверенное владение командной строкой (Linux bash, Windows PowerShell)

Понимание основ сетевых технологий и протоколов (HTTP, REST API)

Знание архитектуры виртуализированных сетевых функций (базовый уровень)

Навыки анализа текстовых файлов журналов

1. Запуск и остановка программного обеспечения

1.1 Запуск программы

Программа поставляется в виде Docker-образа или может быть запущена непосредственно из исходного кода.

Запуск из исходного кода (локально):

bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
eda-server

Запуск с использованием Docker:

bash
docker compose -f docker/docker-compose.yml up --build

При запуске программа выполняет следующие действия:

Загружает конфигурационные параметры из переменных окружения

Инициализирует встроенное хранилище (SQLite)

Запускает встроенный HTTP-сервер для REST API, метрик и управления

Выводит сообщение о готовности с информацией о режиме работы

1.2 Останов программы

Штатная остановка:

Нажмите Ctrl+C (SIGINT) в окне терминала. Программа выполняет:

Установку флага остановки для всех рабочих потоков

Завершение обработки текущих активаций

Закрытие соединений с внешними системами (при наличии)

Закрытие соединения с базой данных

Завершение процесса

Принудительная остановка (только в крайнем случае):

bash
kill -TERM <PID> # Linux
taskkill /PID <PID> # Windows

1.3 Перезапуск программы

Для полного перезапуска остановите программу и запустите заново.

Для перезагрузки конфигурации без остановки используйте динамический reload через REST API.

2. Консоль управления и REST API

Управление осуществляется через встроенный REST API.

2.1 Доступ к REST API

Базовый URL: http://127.0.0.1:8080

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

Интерактивная документация OpenAPI доступна по адресу: http://localhost:8080/docs

Быстрая проверка доступности:

bash
curl http://127.0.0.1:8080/health

2.2 Команды мониторинга состояния

GET /health — состояние узла

bash
curl http://127.0.0.1:8080/health

Ответ содержит статус работы программы.

GET /version — версия программы

bash
curl http://127.0.0.1:8080/version

GET /metrics — метрики в формате Prometheus

bash
curl http://127.0.0.1:8080/metrics

2.3 Команды управления (требуют аутентификацию при включенном API-ключе)

Для включения аутентификации запустите сервер с переменной окружения EDA_API_KEY=<секрет>. Все запросы к управляющим эндпоинтам должны нести заголовок X-API-Key: <секрет>. Эндпоинты /health и /metrics остаются открытыми.

GET /templates — список шаблонов активации

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/templates

POST /templates — создание шаблона активации

bash
curl -X POST -H "X-API-Key: <token>" -H "Content-Type: application/json" -d '{"name": "vlan-activation", "steps": ["allocate_resources", "configure_vlan", "verify_activation"]}' http://127.0.0.1:8080/templates

GET /network-elements — список управляемых сетевых элементов

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/network-elements

POST /network-elements — регистрация сетевого элемента

bash
curl -X POST -H "X-API-Key: <token>" -H "Content-Type: application/json" -d '{"name": "core-router-1", "type": "vrouter", "ip": "10.0.0.5"}' http://127.0.0.1:8080/network-elements

POST /activations — запуск активации сервиса

bash
curl -X POST -H "X-API-Key: <token>" -H "Content-Type: application/json" -d '{"template_id": "<template_id>", "ne_id": "<ne_id>"}' http://127.0.0.1:8080/activations

GET /activations — список активаций

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/activations

GET /activations/{id}/status — текущее состояние активации

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/activations/<id>/status

GET /activations/{id}/logs — лог выполнения шагов

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/activations/<id>/logs

POST /activations/{id}/deactivate — деактивация (teardown)

bash
curl -X POST -H "X-API-Key: <token>" http://127.0.0.1:8080/activations/<id>/deactivate

POST /activations/{id}/retry — повтор после сбоя

bash
curl -X POST -H "X-API-Key: <token>" http://127.0.0.1:8080/activations/<id>/retry

POST /activations/batch — пакетная активация

bash
curl -X POST -H "X-API-Key: <token>" -H "Content-Type: application/json" -d @batch_activation.json http://127.0.0.1:8080/activations/batch

GET /alarms — список алармов

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/alarms?active=true

POST /alarms/{id}/clear — снять аларм

bash
curl -X POST -H "X-API-Key: <token>" http://127.0.0.1:8080/alarms/<id>/clear

3. Конфигурирование программы

3.1 Параметры конфигурации

Программа использует переменные окружения для конфигурации.

Секция HTTP и управления:

EDA_API_URL — базовый URL API (по умолчанию http://localhost:8080)
EDA_API_KEY — секретный ключ для аутентификации (опционально)

Секция хранилища:

Используется встроенная SQLite-база данных. Путь к файлу базы данных настраивается через переменные окружения (при необходимости).

Полный каталог конфигурационных параметров в машиночитаемом виде представлен в файле parameters/eda_parameters.json и в читаемом виде в docs/PARAMETERS.md.

3.2 Пример конфигурации (переменные окружения)

bash
EDA_API_URL=http://0.0.0.0:8080
EDA_API_KEY=secure-api-key-change-me

3.3 Изменение конфигурации в процессе эксплуатации

Временное изменение (без перезапуска):

Некоторые параметры могут быть обновлены динамически через REST API (зависит от реализации конкретных эндпоинтов). Для изменения параметров, не поддерживающих динамическое обновление, требуется перезапуск программы.

Постоянное изменение:

Остановите программу (Ctrl+C или через системный сигнал)

Измените необходимые переменные окружения

Запустите программу заново

При развертывании через OpenStack Heat-шаблон параметры задаются в файле env.yaml.

4. Мониторинг и сбор диагностической информации

4.1 Журнал событий

Программа ведёт журнал с выводом на консоль. Формат строки журнала:

text
YYYY-MM-DD HH:MM:SS.mmm [LEVEL] [ИСТОЧНИК] Сообщение

Пример строки журнала:

text
2026-04-07 16:40:05.691 [INFO ] [ActivationEngine] Activation started id=act_123 template=vlan-activation

4.2 Метрики производительности

Программа предоставляет метрики в формате Prometheus на эндпоинте /metrics (порт 8080).

Пример метрик:

text
eda_activations_total{status="active"} 15
eda_activations_total{status="failed"} 2
eda_activations_total{status="held"} 0
eda_activation_steps_total{step="configure_vlan", status="success"} 10
eda_activation_steps_total{step="configure_vlan", status="failed"} 1
eda_alarms_active_total 0

Получение метрик:

bash
curl http://127.0.0.1:8080/metrics

4.3 Мониторинг использования ресурсов

Процессор и память (Linux):

bash
top -p $(pgrep -f eda-server)

Сетевые порты:

bash
netstat -tulpn | grep 8080

Ожидаемые порты:

Порт 8080 — TCP — HTTP (метрики, health, admin API)

4.4 Сбор диагностического пакета

При возникновении инцидента соберите следующие данные:

Версия программы (из /version или лога при запуске)

Конфигурационные параметры (переменные окружения, удалив секреты)

Вывод REST API:

/health

/version

/metrics

/alarms?active=true

Информация об окружении (Linux):

bash
uname -a
cat /etc/os-release

5. Типовые эксплуатационные процедуры

5.1 Ежедневные операции

Проверка работоспособности:

bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/version
curl http://127.0.0.1:8080/metrics | head -20

Проверка активных алармов:

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/alarms?active=true

Проверка статуса активаций:

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/activations

5.2 Еженедельные операции

Анализ ключевых метрик (количество активаций, успехов, сбоев):

bash
curl http://127.0.0.1:8080/metrics | grep -E "activations_total|alarms"

Проверка состояния шаблонов и зарегистрированных сетевых элементов:

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/templates
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/network-elements

5.3 Ежемесячные операции

Анализ производительности (среднее количество активаций, пиковые нагрузки):

Экспорт метрик за период через внешнюю систему мониторинга (Prometheus).

Резервное копирование базы данных:

bash
cp eda.db eda.db.$(date +%Y%m%d)

Проверка актуальности версии: сравните текущую версию с последним релизом.

5.4 Действия в нештатных ситуациях

Программа не отвечает на HTTP запросы:

Проверьте, запущен ли процесс:

bash
ps aux | grep eda-server # Linux
Get-Process python # Windows

Проверьте, слушается ли порт 8080:

bash
netstat -an | grep 8080

Принудительно остановите и запустите заново.

Активация завершилась со сбоем (FAILED):

Проверьте логи активации:

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/activations/<id>/logs

Проверьте наличие алармов:

bash
curl -H "X-API-Key: <token>" http://127.0.0.1:8080/alarms?active=true

При необходимости выполните повтор:

bash
curl -X POST -H "X-API-Key: <token>" http://127.0.0.1:8080/activations/<id>/retry

Блокировка сетевого элемента (maintenance mode):

Новые активации на заблокированный элемент автоматически переводятся в состояние HELD и возобновляются после разблокировки.

Команды через CLI:

bash
eda-cli ne block <ne_id>
eda-cli ne unblock <ne_id>

Или через API:

bash
curl -X POST -H "X-API-Key: <token>" http://127.0.0.1:8080/network-elements/<id>/block
curl -X POST -H "X-API-Key: <token>" http://127.0.0.1:8080/network-elements/<id>/unblock

6. Взаимодействие со смежными системами

6.1 Проверка доступности

Проверка HTTP порта (8080):

bash
curl -I http://127.0.0.1:8080/health

6.2 Мониторинг с внешних систем

Prometheus экспорт:

EDA предоставляет метрики в формате Prometheus на эндпоинте /metrics (порт 8080).

Интеграция через анализ журнала (syslog):

bash
tail -f /var/log/eda.log | while read line; do
if echo "$line" | grep -q "ERROR|CRITICAL"; then

Отправка alert во внешнюю систему

fi
done

Приложение А. Быстрый справочник команд (REST API)

Метод URL Назначение
GET /health Состояние узла
GET /version Версия программы
GET /metrics Метрики в формате Prometheus
GET /templates Список шаблонов активации (требует токен)
POST /templates Создание шаблона (требует токен)
DELETE /templates/{id} Удаление шаблона (требует токен)
GET /network-elements Список сетевых элементов (требует токен)
POST /network-elements Регистрация NE (требует токен)
DELETE /network-elements/{id} Удаление NE (требует токен)
POST /network-elements/{id}/block Блокировка NE (требует токен)
POST /network-elements/{id}/unblock Разблокировка NE (требует токен)
POST /activations Запуск активации (требует токен)
POST /activations/batch Пакетная активация (требует токен)
GET /activations Список активаций (требует токен)
GET /activations/{id}/status Статус активации (требует токен)
GET /activations/{id}/logs Лог активации (требует токен)
POST /activations/{id}/deactivate Деактивация (требует токен)
POST /activations/{id}/retry Повтор активации (требует токен)
DELETE /activations/{id} Удаление записи (требует токен)
GET /alarms Список алармов (требует токен)
POST /alarms/{id}/clear Снятие аларма (требует токен)

Быстрый скрипт для bash:

bash
BASE="http://127.0.0.1:8080"
TOKEN="your-api-key"

Статус

curl -s "$BASE/health" | jq .

Метрики

curl -s "$BASE/metrics" | head -20

Список активаций

curl -s -H "X-API-Key: TOKEN""TOKEN""BASE/activations" | jq .

Активные алармы

curl -s -H "X-API-Key: TOKEN""TOKEN""BASE/alarms?active=true" | jq .

Приложение Б. Расположение файлов

Файл/директория Назначение
eda/ Исходный код программы
api/ FastAPI-приложение, роутеры, схемы
cli/ eda-cli (CLI-клиент)
core/ Модели, хранилище, движок активации, метрики
config.py Настройки через переменные окружения
server.py Точка входа Uvicorn
docker/ Dockerfile, entrypoint, docker-compose
heat/ Heat-шаблон для OpenStack
tests/ Набор тестов (pytest)
examples/ Примеры JSON для шаблонов, NE, активаций
docs/ Архитектурные заметки, каталог параметров
parameters/ Машиночитаемый каталог параметров