13 KiB
13 KiB
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.docker4.8.1 (используется для управления Docker Compose) - Python: 3.12.3 на управляющем хосте
- Jinja2: 3.1.2
- Доступ по SSH ко всем хостам (настройки в
ansible.cfgили через переменные) - Docker и Docker Compose установлены на целевых хостах (обеспечивается ролью
docker) - Ansible Vault пароль для расшифровки
vault.yml(должен быть доступен при запуске)
Установленные пакеты Python:
ansible11.11.0docker7.1.0
Команды для проверки:
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-файлах.
Базовые команды:
# Проверка синтаксиса плейбука
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 года. По мере изменений в инфраструктуре разделы будут обновляться.