# 09. Ansible — общее описание репозитория ## 🎯 Цель репозитория Автоматизированное развертывание и обслуживание всех сервисов домашнего мультимедиа центра. Сервер стал полноценной частью семьи: дети смотрят мультфильмы, жена слушает аудиокниги, все общаются через голосовой чат или текстовые сообщения с друзьями. Данный репозиторий создан для того, чтобы: - В случае непредвиденной ситуации кто-то из близких мог разобраться в конфигурации и продолжить поддержку сервера. - Я сам мог не помнить всех деталей настройки, которые делал несколько лет назад, и быстро находить нужную информацию. - Воспроизводить развертывание сервисов на новом оборудовании при необходимости. Вся конфигурация описана в виде кода (Infrastructure as Code) с использованием Ansible. --- ## 🖥️ Управляемые хосты Хосты представляют собой LXC-контейнеры в Proxmox, каждый отвечает за свою группу сервисов. Файл инвентаря: `inventories/hosts` ### Группы и хосты | Группа | Хост | IP-адрес | Назначение | |------------------|-----------|-------------|-----------------------------------------| | `pve-server` | proxmox | 192.168.1.200 | Гипервизор Proxmox | | `gateway-server` | gateway | 192.168.1.201 | Шлюз, VPN, роутинг | | `data-server` | data | 192.168.1.202 | Хранилище данных, Samba | | `media-server` | media | 192.168.1.203 | Медиасервисы (Jellyfin, Audiobookshelf)| | `photo-server` | photo | 192.168.1.204 | Фото (Immich) | | `talk-server` | talk | 192.168.1.206 | Коммуникации (Snikket, Mumble) | | `games-server` | games | 192.168.1.207 | Игровые серверы (Minecraft) | | `manage-server` | manage | 192.168.1.208 | Управление (Heimdall, NPM, Grafana) | | `git-server` | git | 192.168.1.209 | GitLab | | `ansible-server` | ansible | 192.168.1.210 | Хост, с которого запускается Ansible | | `torrent-server` | torrent | 192.168.1.211 | Торренты (qBittorrent, TorrServer) | Все хосты используют Python 3 как интерпретатор (`ansible_python_interpreter=/usr/bin/python3`). --- ## 🛠️ Технологии и подходы - **Ansible** — управление конфигурацией. - **Docker Compose** — все сервисы запускаются в контейнерах, конфигурация генерируется через шаблоны. - **Jinja2** — шаблонизация конфигурационных файлов (docker-compose.yml, конфиги сервисов). - **Handlers** — перезапуск сервисов только при изменении конфигурации. - **Групповые переменные** — единый файл `group_vars/all.yml` для общих настроек. - **Ansible Vault** — хранение секретов (пароли, токены) в `vault.yml`. - **Модульность** — каждая роль отвечает за один сервис или задачу. - **Идемпотентность** — повторный запуск плейбука не ломает существующую конфигурацию. --- ## 📂 Структура репозитория | Каталог / файл | Описание | |------------------------------|----------------------------------------------------------------------------------------| | `arhive_roles/` | Роли, которые не используются активно (сохранены для истории) | | `group_vars/` | Переменные для всех хостов (файл `all.yml`) | | `inventories/` | Файлы инвентаря (хосты, группы) | | `roles/` | Основные роли — каждый сервис или задача | | `olimp-deploy.yml` | Главный плейбук, включающий все роли | | `vault.yml` | Зашифрованный файл с секретами (редактируется через `ansible-vault`) | ### Основные роли (`roles/`) | Роль | Назначение | |-----------------------|-------------------------------------------------| | ampache | Музыкальный стриминг-сервер | | audiobookshelf | Сервер для аудиокниг и подкастов | | base_setup | Базовая настройка системы (обновление, пакеты) | | bitwarden | Менеджер паролей (Vaultwarden) | | bookstack | Вики / база знаний | | cadvisor | Мониторинг Docker-контейнеров | | calibre-web | Веб-интерфейс для библиотеки Calibre | | docker | Установка Docker и Docker Compose | | flibusta | Зеркало библиотеки Флибуста (Z-Library) | | gitlab | GitLab CE | | grafana | Визуализация метрик (Grafana + VictoriaMetrics) | | heimdall | Стартовая страница (дашборд) | | immich | Фотогалерея / альтернатива Google Photos | | jellyfin | Медиасервер (видео, музыка) | | loki | Система сбора и хранения логов | | mealie | Менеджер рецептов | | meshcentral | Удалённое управление компьютерами | | minecraft | Игровой сервер Minecraft | | mumble | Голосовой чат (Mumble) | | npm | Nginx Proxy Manager | | promtail | Агент сбора логов для Loki | | proxmox_base_setup | Базовая настройка хостов Proxmox | | proxmox_monitoring | Мониторинг Proxmox (pve_exporter) | | qbittorrent | Торрент-клиент | | snikket | Коммуникационный сервер (XMPP) | | system_cleanup | Очистка системы (логи, временные файлы) | | teamspeak | Голосовой сервер TeamSpeak | | torrserver | Торрент-стриминг (TorrServer) | ### Архивные роли (`arhive_roles/`) | Роль | Описание | |---------------------|-----------------------------------------------------| | dashy | Альтернативный дашборд (не используется) | | [delete]pve_monitoring | Старая версия мониторинга Proxmox (удалена) | | matrix | Сервер Matrix (неактивен) | --- ## 📋 Требования к окружению Для работы с репозиторием необходимы: - **Ansible** (ядро): версия 2.18.10 - **Коллекции**: установлена `community.docker` 4.8.1 (используется для управления Docker Compose) - **Python**: 3.12.3 на управляющем хосте - **Jinja2**: 3.1.2 - **Доступ по SSH** ко всем хостам (настройки в `ansible.cfg` или через переменные) - **Docker и Docker Compose** установлены на целевых хостах (обеспечивается ролью `docker`) - **Ansible Vault** пароль для расшифровки `vault.yml` (должен быть доступен при запуске) **Установленные пакеты Python:** - `ansible` 11.11.0 - `docker` 7.1.0 **Команды для проверки:** ```bash ansible --version # ansible [core 2.18.10] ansible-galaxy collection list | grep community.docker # community.docker 4.8.1 pip list | grep -E "ansible|docker" # ansible 11.11.0 # docker 7.1.0 ``` --- ## 👨‍🏫 Для новичков: что такое Ansible? Если вы никогда раньше не работали с Ansible, вот краткое введение: - **Ansible** — это инструмент автоматизации. Вы описываете желаемое состояние системы в YAML-файлах, а Ansible приводит систему к этому состоянию. - **Плейбук** (playbook) — главный файл, который содержит список «пьес» (plays). Каждая пьеса выполняется на определённой группе хостов и включает набор задач (tasks). - **Роль** (role) — набор задач, переменных, шаблонов и обработчиков, объединённых для решения одной задачи (например, установка Jellyfin). Это помогает организовать код. - **Задача** (task) — конкретное действие: создать каталог, скопировать файл, запустить Docker-контейнер и т.д. - **Модуль** — встроенная функция Ansible (например, `docker_compose`, `copy`, `file`). - **Переменные** — хранят значения, которые могут меняться (пути, порты, имена пользователей). Определяются в `group_vars`, `host_vars`, внутри ролей или в плейбуке. - **Шаблон Jinja2** — файл с расширением `.j2`, в который подставляются переменные. Используется для генерации конфигов. - **Обработчик** (handler) — задача, которая выполняется только в том случае, если её уведомила другая задача (например, перезапуск сервиса после изменения конфига). - **Ansible Vault** — шифрование секретных данных (паролей, ключей) в YAML-файлах. **Базовые команды:** ```bash # Проверка синтаксиса плейбука ansible-playbook olimp-deploy.yml --syntax-check # Запуск плейбука (с запросом пароля vault) ansible-playbook olimp-deploy.yml --ask-vault-pass # Запуск только определённой роли (тег) ansible-playbook olimp-deploy.yml --tags jellyfin # Проверка подключения ко всем хостам ansible all -i inventories/hosts -m ping ``` В следующих разделах документации каждый элемент будет разобран подробно, с примерами и пояснениями. --- ## 📝 Статус Документация актуальна на 23 марта 2026 года. По мере изменений в инфраструктуре разделы будут обновляться.