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 # Главный плейбук, включающий все роли ├── README.md # Краткое описание (может быть заменён на главный документ) └── vault.yml # Зашифрованный файл с секретами (редактируется через ansible-vault)

Каждая роль имеет типовую структуру:

tasks/main.yml — основные задачи.
handlers/main.yml — обработчики (обычно для перезапуска).
templates/*.j2 — шаблоны конфигов.
defaults/main.yml — переменные по умолчанию (для некоторых ролей).
files/ — статические файлы (редко).

📋 Требования к окружению

Для работы с репозиторием необходимы:

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

Команды для проверки:

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 года. По мере изменений в инфраструктуре разделы будут обновляться.

9.7 KiB Raw Blame History Unescape Escape