DevOpsLab/docs/site-yml-guide.md

# Руководство по файлу site.yml

**Автор:** Сергей Антропов  
**Сайт:** https://devops.org.ru

## 📋 Описание

Файл `molecule/default/site.yml` является **универсальным playbook'ом для тестирования Ansible ролей** в контейнерах. Этот файл отвечает за подготовку окружения и установку необходимых утилит внутри контейнеров при запуске тестов.

## 🎯 Назначение

### Основные функции:

1. **Обновление пакетов** в контейнерах при запуске тестов
2. **Установка common tools** для корректной работы тестов
3. **Подготовка окружения** для тестирования ролей
4. **Импорт roles/deploy.yml** для запуска ролей

## 🏗️ Структура файла

### 1. Подготовка окружения для тестирования

```yaml
- name: Подготовка окружения для тестирования
  hosts: all
  become: true
  tasks:
    # Задачи подготовки...
```

**Что делает:**
- Обновляет кеш пакетов для всех поддерживаемых ОС
- Устанавливает необходимые утилиты
- Настраивает пользователя для тестирования
- Создает рабочие директории

### 2. Импорт deploy.yml

```yaml
- import_playbook: ../../roles/deploy.yml
```

**Что делает:**
- Импортирует `roles/deploy.yml` для запуска ролей
- Разделяет логику: `site.yml` - подготовка, `deploy.yml` - роли
- Обеспечивает единую точку управления ролями

## 🐧 Поддерживаемые ОС

### Debian/Ubuntu
- **Менеджер пакетов:** `apt`
- **Обновление:** `apt update`
- **Утилиты:** `curl`, `jq`, `ca-certificates`, `iproute2`, `iputils-ping`, `procps`, `net-tools`, `sudo`, `vim`, `wget`, `unzip`, `git`

### RHEL/CentOS/AlmaLinux/Rocky
- **Менеджер пакетов:** `yum`
- **Обновление:** `yum update_cache`
- **Утилиты:** `curl`, `jq`, `ca-certificates`, `iproute`, `iputils`, `procps-ng`, `net-tools`, `sudo`, `vim`, `wget`, `unzip`, `git`

### Alt Linux
- **Менеджер пакетов:** `apt` (специальная версия)
- **Обновление:** `apt update`
- **Утилиты:** `curl`, `jq`, `ca-certificates`, `iproute2`, `iputils`, `procps`, `net-tools`, `sudo`, `vim`, `wget`, `unzip`, `git`

## 🏷️ Теги (Tags)

### setup
- Обновление пакетов
- Установка утилит
- Настройка пользователей
- Создание директорий

### update
- Обновление кеша пакетов
- Обновление списка пакетов

### tools
- Установка common tools
- Установка системных утилит

### python
- Установка Python 3
- Установка pip
- Установка venv

### user
- Создание тестового пользователя
- Настройка домашней директории

### sudo
- Настройка sudo для тестового пользователя
- Конфигурация прав доступа

### directory
- Создание рабочих директорий
- Настройка прав доступа

### roles
- Запуск тестирования ролей
- Выполнение функциональных тестов

### test
- Тестирование функциональности
- Проверка работоспособности

## 🚀 Использование

### Запуск полного тестирования
```bash
make role test
```

### Запуск только подготовки окружения
```bash
make role test --tags setup
```

### Запуск только обновления пакетов
```bash
make role test --tags update
```

### Запуск только установки утилит
```bash
make role test --tags tools
```

### Запуск только тестирования ролей
```bash
make role test --tags roles
```

## 🔧 Настройка

### Переменные окружения

```bash
# Настройка тестового пользователя
export TEST_USER=testuser

# Настройка рабочей директории
export TEST_DIR=/tmp/ansible-test

# Настройка прав доступа
export TEST_MODE=0755
```

### Кастомизация утилит

Для добавления дополнительных утилит отредактируйте соответствующие секции:

```yaml
# Для Debian/Ubuntu
- name: Install common tools (Debian/Ubuntu)
  apt:
    name:
      - curl
      - jq
      - your-custom-tool  # Добавьте сюда
    state: present
```

## 🐛 Troubleshooting

### Проблема: Ошибка обновления пакетов
**Решение:** Проверьте доступность репозиториев и интернет-соединение

### Проблема: Не удается установить утилиты
**Решение:** Проверьте названия пакетов для конкретной ОС

### Проблема: Ошибка создания пользователя
**Решение:** Проверьте права доступа и существование пользователя

### Проблема: Ошибка настройки sudo
**Решение:** Проверьте синтаксис файла sudoers

## 📊 Мониторинг

### Логи выполнения
```bash
# Просмотр логов тестирования
make role test 2>&1 | tee test.log

# Фильтрация по тегам
grep "TASK \[.*\]" test.log
```

### Проверка установленных утилит
```bash
# В контейнере
which curl jq vim git
```

### Проверка пользователя
```bash
# В контейнере
id testuser
sudo -l -U testuser
```

## 🔄 Автоматическое обновление

Файл `site.yml` автоматически обновляется при добавлении новых ролей:

```bash
# Автоматическое обновление
make update-playbooks
```

**Что происходит:**
1. Обнаруживаются все роли в директории `roles/`
2. Обновляется секция "Тестирование всех ролей"
3. Добавляются новые роли в список

## 📝 Примеры использования

### Тестирование конкретной роли
```bash
# Тестирование только роли ping
make role test minimal ping
```

### Тестирование с конкретным preset'ом
```bash
# Тестирование с preset'ом performance
make role test performance
```

### Отладка проблем
```bash
# Запуск с подробным выводом
make role test --verbose
```

## 🎯 Лучшие практики

1. **Всегда используйте теги** для разделения задач
2. **Проверяйте совместимость** утилит с ОС
3. **Тестируйте на разных образах** перед коммитом
4. **Используйте idempotent задачи** для стабильности
5. **Документируйте изменения** в комментариях

## 🔗 Связанные файлы

- `molecule/default/molecule.yml` - конфигурация Molecule
- `roles/deploy.yml` - playbook для продакшн развертывания
- `inventory/hosts.ini` - инвентори для тестирования
- `Makefile` - команды для запуска тестов