PyGuardian/documentation/examples/cluster-management.md

Управление кластером PyGuardian

🏢 Централизованное развертывание агентов

PyGuardian поддерживает централизованное управление кластером серверов через Telegram бот. Мастер-сервер может автоматически развертывать и управлять агентами на удаленных серверах.

🎯 Возможности кластера

Основные функции:

• Автоматическое развертывание: Установка PyGuardian на удаленные серверы
• Централизованное управление: Контроль всех агентов через один Telegram бот
• Мониторинг статуса: Проверка состояния агентов в реальном времени
• SSH интеграция: Безопасное подключение через SSH ключи или пароли
• Автоматическая очистка: Удаление агентов с очисткой удаленных серверов

Архитектура:

[Master Server] ──SSH──┐
                       ├── [Agent Server 1]
                       ├── [Agent Server 2] 
                       ├── [Agent Server 3]
                       └── [Agent Server N]

🚀 Быстрый старт

1. Настройка мастер-сервера

Убедитесь что в config/config.yaml указано:

cluster:
  cluster_name: "MyCompany-Security"
  master_server: true
  ssh_timeout: 30
  ssh_retries: 3

2. Подготовка SSH доступа

Вариант A: SSH ключи (рекомендуется)

# Генерация ключей
ssh-keygen -t rsa -b 4096 -f ~/.ssh/pyguardian_cluster

# Копирование на целевой сервер
ssh-copy-id -i ~/.ssh/pyguardian_cluster.pub root@192.168.1.100

Вариант B: Пароли (менее безопасно)

Используется для первоначальной настройки или тестирования.

3. Добавление серверов

/add_server web-01 192.168.1.100
/add_server web-02 192.168.1.101 ubuntu 2222
/add_server db-01 192.168.1.200

4. Развертывание агентов

/deploy_agent web-01-192-168-1-100
/deploy_agent web-02-192-168-1-101
/deploy_agent db-01-192-168-1-200

5. Мониторинг кластера

/cluster           # Общая информация
/agents            # Список агентов
/check_agents      # Проверка статуса

📋 Команды управления кластером

Основные команды

Команда	Описание	Пример
/cluster	Информация о кластере	/cluster
/agents	Список всех агентов	/agents
/add_server	Добавить сервер	/add_server web-01 192.168.1.100
/remove_server	Удалить сервер	/remove_server web-01-192-168-1-100
/deploy_agent	Развернуть агент	/deploy_agent web-01-192-168-1-100
/check_agents	Проверить статусы	/check_agents

Детальные примеры

Добавление сервера

# Базовое добавление (root, порт 22)
/add_server web-server 192.168.1.100

# С кастомным пользователем
/add_server app-server 10.0.0.50 ubuntu

# С кастомным портом
/add_server db-server 192.168.1.200 postgres 2222

# Полная форма
/add_server api-server 172.16.0.100 deploy 2200

Развертывание агента

# Обычное развертывание
/deploy_agent web-server-192-168-1-100

# Принудительная переустановка
/deploy_agent web-server-192-168-1-100 force

Удаление сервера

# Простое удаление (агент остается)
/remove_server web-server-192-168-1-100

# С очисткой удаленного сервера
/remove_server web-server-192-168-1-100 cleanup

🔧 Конфигурация

Настройки кластера в config/config.yaml

cluster:
  cluster_name: "Production-Cluster"    # Название кластера
  master_server: true                   # Мастер-сервер
  agents_config_path: "/var/lib/pyguardian/agents.yaml"
  deployment_path: "/opt/pyguardian"
  ssh_timeout: 30                       # Таймаут SSH (секунды)
  ssh_retries: 3                        # Попытки подключения

# SSH ключи по умолчанию (опционально)  
ssh:
  default_key_path: "/root/.ssh/pyguardian_cluster"
  default_user: "root"
  default_port: 22

Файл агентов agents.yaml

cluster:
  name: "Production-Cluster"
  master_server: true
  last_updated: "2024-11-25T15:30:00"

agents:
  web-01-192-168-1-100:
    hostname: "web-01"
    ip_address: "192.168.1.100"
    ssh_port: 22
    ssh_user: "root"
    ssh_key_path: "/root/.ssh/pyguardian_cluster"
    status: "online"
    last_check: "2024-11-25T15:25:00"
    version: "1.0.0"

  api-server-172-16-0-100:
    hostname: "api-server"
    ip_address: "172.16.0.100"
    ssh_port: 2200
    ssh_user: "deploy"
    status: "deployed"
    last_check: null
    version: null

🛡️ Безопасность кластера

Рекомендации по безопасности:

1. SSH ключи: Всегда используйте SSH ключи вместо паролей
2. Ограниченные права: Создайте отдельного пользователя для развертывания
3. Файрвол: Ограничьте SSH доступ только с мастер-сервера
4. Мониторинг: Регулярно проверяйте статус агентов
5. Обновления: Следите за обновлениями PyGuardian

Настройка пользователя для развертывания:

# На целевом сервере
useradd -m -s /bin/bash pyguardian-deploy
usermod -aG sudo pyguardian-deploy

# Настройка sudoers
echo 'pyguardian-deploy ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/pyguardian-deploy

# Копирование SSH ключа
mkdir /home/pyguardian-deploy/.ssh
cp /root/.ssh/authorized_keys /home/pyguardian-deploy/.ssh/
chown -R pyguardian-deploy:pyguardian-deploy /home/pyguardian-deploy/.ssh
chmod 700 /home/pyguardian-deploy/.ssh
chmod 600 /home/pyguardian-deploy/.ssh/authorized_keys

🚨 Устранение неполадок

Частые проблемы:

Ошибка SSH соединения

❌ Не удалось подключиться к серверу: Connection refused

Решение:

1. Проверьте доступность сервера: ping 192.168.1.100
2. Проверьте SSH сервис: ssh root@192.168.1.100
3. Проверьте порт SSH: nmap -p 22 192.168.1.100

Ошибка прав доступа

❌ Ошибка установки: Permission denied

Решение:

1. Убедитесь что пользователь имеет права sudo
2. Проверьте настройки sudoers
3. Попробуйте от root пользователя

Агент не запускается

🔴 service_status: failed

Решение:

1. Проверьте логи: journalctl -u pyguardian-agent -f
2. Проверьте конфигурацию агента
3. Переустановите агент: /deploy_agent agent-id force

Команды диагностики:

# На мастер-сервере
tail -f /var/log/pyguardian.log

# На агенте
systemctl status pyguardian-agent
journalctl -u pyguardian-agent -f
cat /var/log/pyguardian-agent.log

📊 Мониторинг кластера

Telegram уведомления

PyGuardian автоматически отправляет уведомления о:

• Добавлении новых агентов
• Успешном развертывании
• Изменении статуса агентов
• Ошибках подключения

Пример вывода команд:

/cluster

🏢 Кластер Production-Cluster

📊 Статистика:
  • Всего агентов: 5
  • Онлайн: 4
  • Оффлайн: 1
  • Развернуто: 5

🖥️ Агенты:
🟢 web-01 (192.168.1.100)
🟢 web-02 (192.168.1.101)
🔴 db-01 (192.168.1.200)
🟢 api-server (172.16.0.100)
🟢 cache-01 (10.0.0.50)

🕐 Последнее обновление: 2024-11-25 15:30:45

/check_agents

🔍 Результаты проверки агентов

📊 Статистика:
  • Проверено: 5
  • Онлайн: 4  
  • Оффлайн: 1
  • Ошибки: 0

📋 Детали:
🟢 web-01: active
🟢 web-02: active  
🔴 db-01: inactive
🟢 api-server: active
🟢 cache-01: active

🕐 Время проверки: 15:32:10

🔄 Автоматизация

Скрипты автоматизации

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

#!/bin/bash
# auto-deploy.sh - Автоматическое развертывание на список серверов

SERVERS=(
    "web-01 192.168.1.100"
    "web-02 192.168.1.101"
    "api-01 172.16.0.100"
)

for server in "${SERVERS[@]}"; do
    hostname=$(echo $server | cut -d' ' -f1)
    ip=$(echo $server | cut -d' ' -f2)
    
    echo "Добавляю $hostname ($ip)..."
    # Здесь может быть API вызов или автоматизация через expect
done

Интеграция с CI/CD

PyGuardian кластер может быть интегрирован с CI/CD пайплайнами для автоматического развертывания защиты на новые серверы.

📈 Масштабирование

Рекомендации по масштабированию:

• До 10 серверов: Один мастер-сервер
• 10-50 серверов: Мастер + резервный мастер
• 50+ серверов: Распределенная архитектура

Мониторинг производительности:

• Время отклика SSH соединений
• Использование ресурсов мастер-сервера
• Скорость развертывания агентов
• Частота проверки статуса

---

Данная документация покрывает основные возможности управления кластером PyGuardian. Для дополнительной помощи обращайтесь к основной документации проекта.