# 09. Ansible — общие роли (common)

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

---

## 1. base_setup

### Назначение
Базовая настройка всех хостов (кроме Proxmox). Выполняется первой.

### Структура
```mermaid
graph TD
    base_setup/ --> handlers/
    base_setup/ --> tasks/
    handlers/ --> main.yml
    tasks/ --> main.yml
```

### Выполняемые задачи
- Установка базовых пакетов (`base_packages`).
- Создание пользовательских директорий (`custom_directories`).
- Настройка временной зоны (`timezone`).
- Настройка локали (`system_locale`).
- Добавление публичных SSH-ключей (`ssh_public_keys`).

### Используемые переменные (из `group_vars/all.yml`)
- `timezone`
- `system_locale`
- `base_packages`
- `custom_directories`
- `ssh_public_keys`

### Обработчики
- `reload systemd` — применяется, если были изменения в юнитах (редко).

### Примечания
- Роль идемпотентна: повторный запуск не меняет уже существующие настройки.

---

## 2. docker

### Назначение
Установка Docker Engine и Docker Compose на целевой хост.

### Структура
```mermaid
graph TD
    docker/ --> tasks/
    tasks/ --> main.yml
```

### Выполняемые задачи
- Добавление официального репозитория Docker.
- Установка пакетов: `docker-ce`, `docker-ce-cli`, `containerd.io`, `docker-compose-plugin`.
- Запуск и включение службы Docker.
- Добавление пользователя `admin_user` в группу `docker`.

### Используемые переменные
- `admin_user` (из `group_vars/all.yml`) — пользователь, добавляемый в группу `docker`.

### Примечания
- Не требует обработчиков; Docker управляется системой.
- После установки можно запускать контейнеры от имени администратора.

---

## 3. system_cleanup

### Назначение
Удаление ненужных пакетов и очистка системы.

### Структура
```mermaid
graph TD
    system_cleanup/ --> defaults/
    system_cleanup/ --> tasks/
    defaults/ --> main.yml
    tasks/ --> main.yml
```

### Выполняемые задачи
- Удаление пакетов из списка `cleanup_packages`.
- Автоматическое удаление неиспользуемых зависимостей (`apt autoremove`).
- Очистка кэша пакетов (`apt autoclean`).

### Используемые переменные
- `cleanup_packages` (из `group_vars/all.yml`) — список пакетов для удаления.
- (В `defaults/main.yml` задан пустой список, переопределяется в групповых переменных.)

### Примечания
- Роль безопасна: удаляет только явно указанные пакеты.
- Рекомендуется запускать периодически для поддержания чистоты системы.

---

## 4. promtail

### Назначение
Установка и настройка Promtail — агента сбора логов для Loki.

### Структура
```mermaid
graph TD
    promtail/ --> handlers/
    promtail/ --> tasks/
    promtail/ --> templates/
    handlers/ --> main.yml
    tasks/ --> main.yml
    templates/ --> promtail-config.yml.j2
    templates/ --> promtail-service.yml.j2
```

### Выполняемые задачи
- Создание пользователя `promtail`.
- Создание директорий для конфигурации и данных.
- Генерация конфигурации из шаблона `promtail-config.yml.j2`.
- Установка systemd-сервиса из шаблона `promtail-service.yml.j2`.
- Запуск и включение сервиса.

### Используемые переменные (из `group_vars/all.yml`)
- `monitoring_ports.promtail` — порт для работы Promtail.
- `loki_server_host` и `loki_server_port` — адрес Loki.
- `promtail_config_dir` — директория конфигурации.
- `promtail_data_dir` — директория для позиций.

### Обработчики
- `restart promtail` — перезапуск сервиса при изменении конфигурации.

### Примечания
- Promtail отправляет логи только на указанный Loki.
- Настраивается только на серверах из `monitoring_groups.promtail_servers`.

---

## 5. proxmox_base_setup

### Назначение
Базовая настройка хостов Proxmox (гипервизоров).

### Структура
```mermaid
graph TD
    proxmox_base_setup/ --> handlers/
    proxmox_base_setup/ --> tasks/
    handlers/ --> main.yml
    tasks/ --> main.yml
```

### Выполняемые задачи
- Настройка репозиториев Proxmox (переключение на No-subscription).
- Обновление системы.
- Установка дополнительных пакетов (если указаны).
- Настройка времени и локали (аналогично `base_setup`).

### Используемые переменные
- `timezone`, `system_locale` — как в `base_setup`.

### Обработчики
- `reload systemd` — при изменениях.

### Примечания
- Применяется только к группе `pve-server`.

---

## 6. proxmox_monitoring

### Назначение
Настройка мониторинга на Proxmox: установка Node Exporter и Proxmox Exporter.

### Структура
```mermaid
graph TD
    proxmox_monitoring/ --> handlers/
    proxmox_monitoring/ --> tasks/
    proxmox_monitoring/ --> templates/
    handlers/ --> main.yml
    tasks/ --> main.yml
    templates/ --> node_exporter.service.j2
    templates/ --> pve_exporter_config.yml.j2
    templates/ --> storcli_metrics.sh.j2
```

### Выполняемые задачи
- Установка Node Exporter (для сбора метрик ОС).
- Установка Proxmox Exporter (для сбора метрик PVE).
- Генерация конфигурации Proxmox Exporter с токеном доступа.
- Создание systemd-сервисов для обоих экспортеров.
- (Опционально) Установка скрипта `storcli_metrics.sh` для сбора метрик RAID-контроллера (если LSI MegaRAID).

### Используемые переменные (из `group_vars/all.yml`)
- `monitoring_ports.node_exporter`
- `monitoring_ports.proxmox_exporter`
- `pve_exporter_user`, `pve_exporter_token_name`, `pve_exporter_token_value`
- `admin_user`

### Обработчики
- `restart node_exporter` — перезапуск Node Exporter.
- `restart proxmox_exporter` — перезапуск Proxmox Exporter.

### Примечания
- Токен для Proxmox Exporter хранится в `vault.yml`.
- Node Exporter собирает метрики хоста, Proxmox Exporter — метрики виртуальных окружений.

---

*Далее: [Роли Gateway](09-ansible-roles-gateway.md)*