# 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

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