SensusAgent/docs/ansible_groups.md

# Гибкая конфигурация коллекторов через Ansible группы

**Автор:** Сергей Антропов  
**Сайт:** https://devops.org.ru

## Обзор

Система позволяет гибко настраивать, какие коллекторы запускать на разных типах серверов через Ansible группы и переменные.

## Структура

```
runner/
├── group_vars/           # Переменные для групп хостов
│   ├── all.yml          # Глобальные настройки
│   ├── proxmox.yml      # Настройки для Proxmox нод
│   ├── proxvms.yml      # Настройки для VM/контейнеров
│   └── standalone.yml   # Настройки для автономных серверов
├── templates/
│   ├── config.yaml.j2   # Шаблон конфигурации
│   └── sensusagent.service.j2  # Шаблон systemd сервиса
└── inventory.ini        # Группы хостов
```

## Группы хостов

### 1. **proxmox** - Proxmox ноды
**Коллекторы:** `proxcluster`, `proxnode`, `proxvms`, `uptime`

```ini
[proxmox]
pnode10 ansible_host=10.14.253.20 ansible_user=devops
```

**Назначение:** Сбор информации о Proxmox кластере, нодах и виртуальных машинах.

### 2. **proxvms** - VM и контейнеры Proxmox
**Коллекторы:** `proxvmsystem`, `uptime`

```ini
[proxvms]
kube-dbrain-node01 ansible_host=10.14.246.75 ansible_user=devops
kube-data ansible_host=10.14.246.150 ansible_user=devops
```

**Назначение:** Сбор системных метрик с уникальным `machine_uid` для идентификации.

### 3. **standalone** - Автономные серверы
**Коллекторы:** `system`, `hba`, `sensors`, `uptime`

```ini
[standalone]
server1 ansible_host=1.2.3.4 ansible_user=root
```

**Назначение:** Сбор системных метрик, информации о RAID/HBA и датчиках.

## Конфигурация групп

### Настройки systemd сервиса

В файле `group_vars/all.yml` можно настроить глобальные параметры systemd сервиса:

```yaml
# Настройки systemd сервиса
service_user: root
service_group: root
service_restart_sec: 3
agent_mode: kafka
```

Для разных групп можно переопределить эти настройки:

```yaml
# group_vars/proxvms.yml
agent_mode: stdout  # VM/контейнеры могут использовать stdout вместо kafka
```

### Файл `group_vars/proxmox.yml`

```yaml
# Список коллекторов для группы proxmox
collectors_enabled:
  - proxcluster
  - proxnode
  - proxvms
  - uptime

# Дополнительные настройки
collectors_config:
  proxcluster:
    interval: "60s"
    timeout: "30s"
  proxnode:
    interval: "30s"
    timeout: "15s"
  proxvms:
    interval: "300s"
    timeout: "60s"
  uptime:
    interval: "60s"
    timeout: "5s"
```

### Файл `group_vars/proxvms.yml`

```yaml
# Список коллекторов для VM/контейнеров
collectors_enabled:
  - proxvmsystem
  - uptime

# Настройки
collectors_config:
  proxvmsystem:
    interval: "300s"
    timeout: "60s"
  uptime:
    interval: "60s"
    timeout: "5s"
```

### Файл `group_vars/standalone.yml`

```yaml
# Список коллекторов для автономных серверов
collectors_enabled:
  - system
  - hba
  - sensors
  - uptime

# Настройки
collectors_config:
  system:
    interval: "30s"
    timeout: "8s"
  hba:
    interval: "300s"
    timeout: "15s"
  sensors:
    interval: "60s"
    timeout: "10s"
  uptime:
    interval: "60s"
    timeout: "5s"
```

## Шаблоны

### Шаблон конфигурации

Файл `templates/config.yaml.j2` автоматически генерирует `config.yaml` на основе переменных групп:

```yaml
# Конфигурация SensusAgent
# Автоматически сгенерировано на основе групповых переменных

agent:
  log_level: "{{ agent_log_level | default('info') }}"
  kafka:
    brokers: "{{ kafka_brokers | default('localhost:9092') }}"
    topic: "{{ kafka_topic | default('sensus-metrics') }}"

collectors:
{% for collector_name in collectors_enabled %}
  {{ collector_name }}:
    enabled: true
    type: exec
    key: {{ collector_name }}
    interval: "{{ collectors_config[collector_name].interval | default('60s') }}"
    timeout: "{{ collectors_config[collector_name].timeout | default('30s') }}"
    exec: "./collectors/{{ collector_name }}"
    platforms: [{{ collectors_config[collector_name].platforms | default('linux') | join(', ') }}]
{% endfor %}
```

### Шаблон systemd сервиса

Файл `templates/sensusagent.service.j2` автоматически генерирует systemd unit на основе переменных групп:

```ini
[Unit]
Description=SensusAgent metrics collector
After=network.target

[Service]
Type=simple
Environment=CONFIG_PATH={{ remote_dir }}/config.yaml
ExecStart={{ remote_dir }}/agent --mode {{ agent_mode | default('kafka') }}
Restart=on-failure
RestartSec={{ service_restart_sec | default(3) }}
User={{ service_user | default('root') }}
Group={{ service_group | default('root') }}

[Install]
WantedBy=multi-user.target
```

## Использование

### 1. Добавление нового хоста

```ini
# В inventory.ini
[proxmox]
new-pnode ansible_host=10.14.253.21 ansible_user=devops
```

### 2. Создание новой группы

1. **Добавить группу в `inventory.ini`:**
```ini
[new_group]
server1 ansible_host=1.2.3.4 ansible_user=root
```

2. **Создать файл `group_vars/new_group.yml`:**
```yaml
collectors_enabled:
  - system
  - uptime

collectors_config:
  system:
    interval: "60s"
    timeout: "10s"
  uptime:
    interval: "120s"
    timeout: "5s"
```

3. **Добавить в `[targets:children]`:**
```ini
[targets:children]
proxmox
proxvms
standalone
new_group
```

### 3. Изменение коллекторов для группы

Отредактируйте соответствующий файл в `group_vars/`:

```yaml
# Добавить новый коллектор
collectors_enabled:
  - system
  - gpu        # Новый коллектор
  - uptime

# Настроить параметры
collectors_config:
  gpu:
    interval: "300s"
    timeout: "30s"
```

### 4. Тестирование конфигурации

```bash
# Запустить тест генерации конфигурации
./runner/test-config-generation.sh

# Развернуть на конкретной группе
ansible-playbook -i runner/inventory.ini runner/deploy-service/playbook.yml --limit proxmox

# Обновление systemd-сервиса (рекомендуется)
make update-service

# Обновление агента без systemd
make update
```

## Примеры конфигураций

### Для Kubernetes нод

```yaml
# group_vars/kubernetes.yml
collectors_enabled:
  - system
  - kubernetes
  - docker
  - uptime

collectors_config:
  system:
    interval: "30s"
    timeout: "8s"
  kubernetes:
    interval: "60s"
    timeout: "30s"
  docker:
    interval: "120s"
    timeout: "15s"
  uptime:
    interval: "60s"
    timeout: "5s"
```

### Для GPU серверов

```yaml
# group_vars/gpu_servers.yml
collectors_enabled:
  - system
  - gpu
  - sensors
  - uptime

collectors_config:
  system:
    interval: "30s"
    timeout: "8s"
  gpu:
    interval: "60s"
    timeout: "30s"
  sensors:
    interval: "120s"
    timeout: "10s"
  uptime:
    interval: "60s"
    timeout: "5s"
```

## Преимущества

1. **Гибкость** - легко настраивать коллекторы для разных типов серверов
2. **Масштабируемость** - простое добавление новых групп и хостов
3. **Централизованное управление** - все настройки в одном месте
4. **Автоматизация** - автоматическая генерация конфигурации
5. **Совместимость** - работает с существующими playbook

## Совместимость

Система полностью совместима с существующими:
- Makefile командами (`make deploy-service`, `make delete-service`)
- Ansible playbook
- Структурой проекта

Группа `[targets:children]` обеспечивает обратную совместимость с существующими скриптами.