feat: Полная переработка документации и структуры проекта
- Переписан главный README.md с подробной навигацией - Создана структурированная документация в docs/: - getting-started.md - быстрый старт - creating-roles.md - создание ролей - cicd-setup.md - настройка CI/CD - monitoring.md - мониторинг и диагностика - site-yml-guide.md - руководство по site.yml - molecule-guide.md - подробное руководство по Molecule - Переписан dockerfiles/README.md с детальным описанием всех образов - Перенесен deploy.yml из корня в roles/ для лучшей организации - Обновлен site.yml для импорта roles/deploy.yml - Добавлены fallback значения в create.yml для надежности - Созданы скрипты автоматизации: - update-playbooks.sh - обновление playbook'ов - generate-role-docs.sh - генерация документации - setup-cicd.sh - настройка CI/CD - Добавлен env.example с примерами переменных - Обновлен Makefile с новыми командами автоматизации - Улучшена навигация по документации
This commit is contained in:
Сергей Антропов
248
docs/site-yml-guide.md
Normal file
248
docs/site-yml-guide.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# Руководство по файлу 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` - команды для запуска тестов
|
||||
Reference in New Issue
Block a user