# AnsibleLab - Универсальная система тестирования Ansible ролей

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

## 🚀 Описание

AnsibleLab - это универсальная система для тестирования Ansible ролей с использованием Docker, Molecule и различных preset'ов конфигурации. Система поддерживает multi-arch сборку, CI/CD интеграцию и работу с различными операционными системами.

## 📚 Документация

### 🚀 Быстрый старт
- **[docs/getting-started.md](docs/getting-started.md)** - Установка, настройка и первое тестирование

### 🛠️ Разработка
- **[docs/creating-roles.md](docs/creating-roles.md)** - Создание и разработка ролей
- **[docs/site-yml-guide.md](docs/site-yml-guide.md)** - Руководство по файлу site.yml
- **[docs/molecule-guide.md](docs/molecule-guide.md)** - Подробное руководство по Molecule
- **[docs/all-images-preset.md](docs/all-images-preset.md)** - Пресет all-images для тестирования всех образов
- **[docs/deploy-yml-customization.md](docs/deploy-yml-customization.md)** - Полное руководство по кастомизации deploy.yml
- **[dockerfiles/README.md](dockerfiles/README.md)** - Подробная документация по Docker образам

### 🏗️ CI/CD
- **[docs/cicd-setup.md](docs/cicd-setup.md)** - Настройка CI/CD для GitHub Actions, Azure DevOps, Jenkins, GitLab CI

### 📊 Мониторинг
- **[docs/monitoring.md](docs/monitoring.md)** - Мониторинг, диагностика и troubleshooting

## ✨ Ключевые возможности

### 🐳 Multi-Arch Docker поддержка
- **Поддерживаемые архитектуры:** amd64, arm64, riscv64, ppc64le, s390x, 386, arm/v7, arm/v6
- **Автоматическая сборка** для всех архитектур одновременно
- **Docker Hub интеграция** с автоматической публикацией
- **Собственные образы** для различных ОС (Ubuntu, Debian, RHEL, CentOS, AlmaLinux, Rocky Linux, ALT Linux, Astra Linux, RED OS)

### 🧪 Универсальная система тестирования
- **Preset система** - любой preset без изменения Makefile
- **Molecule интеграция** с поддержкой Docker
- **Автоматическое создание** тестовых окружений
- **Поддержка systemd** в контейнерах
- **DinD/DOoD** поддержка для Docker функциональности
- **Интерактивное управление ролями** - создание, удаление, просмотр ролей
- **Автоматическое обновление** playbook'ов при добавлении новых ролей
- **Комплексное тестирование** всех образов одновременно (all-images preset)

### 🔐 Безопасность и секреты
- **Ansible Vault** интеграция
- **Автоматическое шифрование/расшифровка** секретов
- **Сканирование** на наличие незашифрованных секретов
- **Управление паролями** и ключами

### 🚀 CI/CD интеграция
- **GitHub Actions** готовые workflow'ы
- **Azure DevOps** pipeline конфигурации
- **Jenkins** pipeline скрипты
- **GitLab CI** интеграция
- **Автоматическое тестирование** при push/PR

## 📁 Структура проекта

```
AnsibleLab/
├── molecule/                    # Molecule конфигурация
│   ├── default/                # Основная конфигурация
│   │   ├── create.yml          # Создание тестовых контейнеров
│   │   ├── converge.yml        # Запуск тестов
│   │   ├── destroy.yml         # Удаление контейнеров
│   │   ├── site.yml           # Основной playbook
│   │   └── molecule.yml        # Конфигурация Molecule
│   └── presets/               # Preset'ы конфигурации
│       ├── default.yml        # Стандартный preset (2 хоста)
│       ├── minimal.yml       # Минимальный preset (1 хост)
│       ├── standard.yml      # Расширенный preset (3 хоста)
│       ├── performance.yml   # Performance preset (5 хостов)
│       ├── security.yml      # Security preset (3 хоста)
│       └── etcd-patroni.yml  # etcd-patroni preset
├── roles/                     # Ansible роли
│   ├── ping/                 # Пример роли ping
│   └── deploy.yml            # 🚀 Playbook для продакшн развертывания
│                              #   (перенесен из корня для лучшей организации)
├── dockerfiles/              # Docker образы для разных ОС
│   ├── ansible-controller/   # Ansible контроллер
│   ├── ubuntu/               # Ubuntu образ
│   ├── debian/              # Debian образ
│   ├── rhel/                # RHEL образ
│   ├── centos/              # CentOS образ
│   ├── alma/                # AlmaLinux образ
│   ├── rocky/               # Rocky Linux образ
│   ├── alt-linux/           # ALT Linux образ
│   ├── astra-linux/         # Astra Linux образ
│   ├── redos/               # RED OS образ
│   └── README.md            # 📖 [Подробная документация](dockerfiles/README.md)
├── cicd/                     # CI/CD конфигурации
│   ├── github/              # GitHub Actions
│   ├── azure-devops/        # Azure DevOps
│   ├── jenkins/             # Jenkins
│   └── gitlab/              # GitLab CI
├── vault/                    # Зашифрованные секреты
├── inventory/                # Инвентори файлы
├── scripts/                  # Скрипты автоматизации
├── docs/                     # 📖 Документация
│   ├── getting-started.md    # 🚀 Быстрый старт
│   ├── creating-roles.md     # 🛠️ Создание ролей
│   ├── cicd-setup.md         # 🏗️ Настройка CI/CD
│   ├── monitoring.md         # 📊 Мониторинг и диагностика
│   ├── site-yml-guide.md     # 📋 Руководство по site.yml
│   └── molecule-guide.md     # 🧪 Подробное руководство по Molecule
├── Makefile                  # Основные команды
├── requirements.yml          # Ansible коллекции
├── ansible.cfg              # Конфигурация Ansible
└── Dockerfile               # Основной Docker образ
```

## 📋 Важные изменения

### Перемещение deploy.yml
**Файл `deploy.yml` перенесен из корня проекта в папку `roles/`** для лучшей организации структуры проекта. Теперь все playbook'и находятся в одном месте.

**Новое расположение:** `roles/deploy.yml`  
**Старое расположение:** `deploy.yml` (в корне)

Все пути в проекте автоматически обновлены. Если вы используете старые скрипты или документацию, обновите пути с `deploy.yml` на `roles/deploy.yml`.

## 🚀 Быстрый старт

> 📖 **Подробное руководство:** [docs/getting-started.md](docs/getting-started.md)

### 1. Клонирование и настройка

```bash
git clone https://github.com/your-username/AnsibleLab.git
cd AnsibleLab

# Копирование переменных окружения
cp env.example .env
```

### 2. Настройка Docker

```bash
# Настройка multi-arch builder
make docker setup-builder

# Сборка всех образов (multi-arch)
make docker build

# Проверка собранных образов
make docker info
```

### 3. Управление ролями

```bash
# Просмотр всех ролей
make role list

# Создание новой роли (интерактивно)
make role create

# Удаление роли (интерактивно)
make role delete
```

### 4. Тестирование ролей

```bash
# Просмотр доступных preset'ов
make presets list

# Тестирование с default preset
make role test

# Тестирование с minimal preset
make role test minimal

# Тестирование всех образов (9 контейнеров)
make role test all-images

# Тестирование с custom preset
make role test my-custom-preset
```

## 🧪 Тестирование

### Preset система

Система поддерживает неограниченное количество preset'ов без изменения Makefile:

```bash
# Просмотр всех доступных preset'ов
make presets list

# Информация о конкретном preset'е
make presets info PRESET=etcd-patroni

# Тестирование с preset'ом
make presets test PRESET=performance
```

### Доступные preset'ы

| Preset | Описание | Хосты | Использование |
|--------|----------|-------|---------------|
| `default` | Стандартный preset | 2 хоста (Debian + RHEL) | Базовое тестирование |
| `minimal` | Минимальный preset | 1 хост (Debian) | Быстрое тестирование |
| `all-images` | **Все образы** | 9 хостов (все ОС) | **Комплексное тестирование** |
| `standard` | Расширенный preset | 3 хоста (Debian + RHEL + Debian) | Полное тестирование |
| `performance` | Performance preset | 5 хостов (Debian + RHEL) | Нагрузочное тестирование |
| `security` | Security preset | 3 хоста (Debian + RHEL) | Тестирование безопасности |
| `etcd-patroni` | etcd-patroni preset | 3 хоста (Debian + RHEL) | Тестирование кластеров |
| `[custom]` | Любой custom preset | Любое количество | Пользовательские сценарии |

### Тестирование с собственными образами

```bash
# Проверка наличия собственных образов
make custom-images check

# Тестирование с собственными образами
make custom-images test minimal
make custom-images test full
make custom-images test performance
```

## 🐳 Docker образы

> 📖 **Подробная документация:** [dockerfiles/README.md](dockerfiles/README.md)

### Multi-Arch поддержка

Система поддерживает сборку для множества архитектур:

```bash
# Настройка builder'а
make docker setup-builder

# Сборка всех образов
make docker build

# Сборка отдельного образа
make docker build-image IMAGE=ubuntu

# Полная пересборка с очисткой кеша
make docker rebuild
```

### Доступные образы

| Образ | Базовый образ | Описание |
|-------|---------------|----------|
| `ansible-controller` | `ubuntu:22.04` | Ansible контроллер с коллекциями |
| `ubuntu` | `ubuntu:22.04` | Ubuntu с systemd |
| `debian` | `debian:bookworm` | Debian с systemd |
| `rhel` | `registry.access.redhat.com/ubi8/ubi` | RHEL с systemd |
| `centos` | `quay.io/centos/centos:stream9` | CentOS Stream с systemd |
| `alma` | `almalinux:8` | AlmaLinux с systemd |
| `rocky` | `rockylinux:8` | Rocky Linux с systemd |
| `alt-linux` | `altlinux/p9` | ALT Linux с systemd |
| `astra-linux` | `astralinux/astra-1.7` | Astra Linux с systemd |
| `redos` | `redos/redos:9` | RED OS с systemd |

### Управление образами

```bash
# Информация об образах
make docker info

# Отправка в Docker Hub
make docker push

# Загрузка из Docker Hub
make docker pull

# Очистка локальных образов
make docker clean

# Диагностика проблем
make docker diagnose

# Сброс builder'а
make docker reset-builder
```

## 🔐 Управление секретами

### Ansible Vault

```bash
# Инициализация vault
make vault init

# Создание файла секретов
make vault create

# Редактирование секретов
make vault edit

# Просмотр секретов
make vault show

# Удаление файла секретов
make vault delete

# Шифрование файла
make vault encrypt

# Расшифровка файла
make vault decrypt

# Смена пароля
make vault rekey

# Проверка vault файлов
make vault check

# Поиск потенциальных секретов
make vault scan
```

## 🚀 Развертывание

### Тестирование (Docker контейнеры)

```bash
# Тестирование с разными preset'ами
make role test                    # default preset
make role test minimal           # minimal preset
make role test standard          # standard preset  
make role test performance       # performance preset
make role test security          # security preset
make role test my-custom-preset  # любой custom preset
```

**Инвентори для тестирования:**
- **Источник:** Динамически создается из preset файлов (`molecule/presets/*.yml`)
- **Расположение:** `${MOLECULE_EPHEMERAL_DIRECTORY}/inventory/hosts.ini`
- **Содержимое:** Временные контейнеры (u1, u2, u3, docker1, dood1)
- **Сеть:** Docker сеть `labnet`
- **Пользователь:** `ansible` (с sudo правами)

**Пример динамического инвентори для тестирования:**
```ini
# Автоматически создается из preset файла
[test]
u1 ansible_host=172.20.0.2 ansible_user=ansible ansible_ssh_private_key_file=/tmp/ssh_key
u2 ansible_host=172.20.0.3 ansible_user=ansible ansible_ssh_private_key_file=/tmp/ssh_key

[web]
u1
u2

[docker]
docker1 ansible_host=172.20.0.4 ansible_user=ansible ansible_ssh_private_key_file=/tmp/ssh_key

[dood]
dood1 ansible_host=172.20.0.5 ansible_user=ansible ansible_ssh_private_key_file=/tmp/ssh_key
```

### Развертывание (Реальные серверы)

```bash
# Развертывание на реальные серверы
make role deploy                 # развертывание ролей
```

**Инвентори для продакшн развертывания:**
- **Источник:** Статический файл `inventory/hosts.ini`
- **Расположение:** `inventory/hosts.ini`
- **Содержимое:** Реальные серверы с SSH подключением
- **Сеть:** Интернет или внутренняя сеть
- **Пользователь:** `devops` (настраивается в `ansible.cfg`)

**Пример продакшн инвентори:**
```ini
# inventory/hosts.ini - Реальные серверы
[web_servers]
web1.example.com ansible_host=192.168.1.10 ansible_user=devops
web2.example.com ansible_host=192.168.1.11 ansible_user=devops

[db_servers]
db1.example.com ansible_host=192.168.1.20 ansible_user=devops
db2.example.com ansible_host=192.168.1.21 ansible_user=devops

[monitoring]
mon1.example.com ansible_host=192.168.1.30 ansible_user=devops

[all:vars]
ansible_ssh_private_key_file=~/.ssh/id_rsa
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
```

### Различия между тестовым и продакшн инвентори

| Параметр | Тестовый инвентори | Продакшн инвентори |
|----------|-------------------|-------------------|
| **Источник** | Динамически из preset файлов | Статический файл `inventory/hosts.ini` |
| **Расположение** | `${MOLECULE_EPHEMERAL_DIRECTORY}/inventory/hosts.ini` | `inventory/hosts.ini` |
| **Хосты** | Временные Docker контейнеры | Реальные серверы |
| **Сеть** | Docker сеть `labnet` | Интернет/внутренняя сеть |
| **Пользователь** | `ansible` (в контейнере) | `devops` (на реальных серверах) |
| **SSH ключи** | Автоматически генерируются | Используются существующие |
| **Время жизни** | Временные (удаляются после тестов) | Постоянные |
| **Подключение** | Docker exec | SSH |

### Настройка продакшн инвентори

**1. Создание файла `inventory/hosts.ini`:**
```ini
# Продакшн серверы
[web_servers]
web1.example.com ansible_host=192.168.1.10
web2.example.com ansible_host=192.168.1.11

[db_servers]
db1.example.com ansible_host=192.168.1.20
db2.example.com ansible_host=192.168.1.21

[monitoring]
mon1.example.com ansible_host=192.168.1.30

# Группы для развертывания
[production:children]
web_servers
db_servers
monitoring

# Общие переменные
[all:vars]
ansible_user=devops
ansible_ssh_private_key_file=~/.ssh/id_rsa
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
```

**2. Настройка SSH ключей:**
```bash
# Генерация SSH ключа (если нет)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa

# Копирование ключа на серверы
ssh-copy-id devops@web1.example.com
ssh-copy-id devops@web2.example.com
ssh-copy-id devops@db1.example.com
```

**3. Тестирование подключения:**
```bash
# Проверка подключения к серверам
ansible all -i inventory/hosts.ini -m ping

# Проверка конкретной группы
ansible web_servers -i inventory/hosts.ini -m ping
```

### Особенности развертывания

**Dry-run проверка:**
```bash
# Проверка без изменений
make role deploy
# Выполняется: ansible-playbook -i inventory/hosts.ini roles/deploy.yml --check
```

**Подтверждение развертывания:**
   ```bash
# Интерактивное подтверждение
make role deploy
# Запрашивается подтверждение: "Продолжить развертывание? (y/N):"
   ```

**Логирование и мониторинг:**
   ```bash
# Подробные логи
ANSIBLE_STDOUT_CALLBACK=yaml make role deploy

# Сохранение логов
make role deploy 2>&1 | tee deployment.log
```

## 🔧 Вспомогательные команды

### Управление ролями

```bash
# Просмотр всех ролей
make role list

# Создание новой роли (интерактивно)
make role create

# Удаление роли (интерактивно)
make role delete

# Проверка синтаксиса ролей
make role lint
```

### Docker команды

```bash
# Очистка Docker ресурсов
make docker clean

# Полная очистка Docker (ОСТОРОЖНО!)
make docker purge

# Обновление всех образов
make docker update
```

### Другие команды

```bash
# Создание секретов
make vault create

# Полная справка
make help
```

## 🏗️ CI/CD интеграция

> 📖 **Подробное руководство:** [docs/cicd-setup.md](docs/cicd-setup.md)

### GitHub Actions

```yaml
# .github/workflows/ansible-test.yml
name: Ansible Testing
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install ansible ansible-lint
          ansible-galaxy collection install -r requirements.yml
      - name: Run lint
        run: make role lint

  test:
    runs-on: ubuntu-latest
    needs: lint
    strategy:
      matrix:
        preset: [minimal, default, performance]
    steps:
      - uses: actions/checkout@v4
      - name: Setup Docker
        run: |
          sudo systemctl start docker
          sudo usermod -aG docker $USER
      - name: Run tests
        run: make role test ${{ matrix.preset }}

  deploy-check:
    runs-on: ubuntu-latest
    needs: [lint, test]
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Check deployment
        run: make role deploy
        env:
          ANSIBLE_HOST_KEY_CHECKING: false
```

### Azure DevOps

```yaml
# azure-pipelines.yml
trigger:
- main
- develop

pool:
  vmImage: 'ubuntu-latest'

variables:
  ANSIBLE_FORCE_COLOR: 'true'
  DOCKER_TLS_CERTDIR: ''

stages:
- stage: Lint
  displayName: 'Lint Stage'
  jobs:
  - job: LintJob
    displayName: 'Run Lint'
    steps:
    - task: UsePythonVersion@0
      inputs:
        versionSpec: '3.11'
    - script: |
        pip install ansible ansible-lint
        ansible-galaxy collection install -r requirements.yml
        make role lint
      displayName: 'Run Ansible Lint'

- stage: Test
  displayName: 'Test Stage'
  dependsOn: Lint
  jobs:
  - job: TestJob
    displayName: 'Run Tests'
    strategy:
      matrix:
        minimal:
          preset: minimal
        default:
          preset: default
        performance:
          preset: performance
    steps:
    - task: UsePythonVersion@0
      inputs:
        versionSpec: '3.11'
    - script: |
        pip install ansible ansible-lint
        ansible-galaxy collection install -r requirements.yml
        make role test $(preset)
      displayName: 'Run Molecule Tests'
      env:
        PRESET: $(preset)

- stage: Deploy
  displayName: 'Deploy Stage'
  dependsOn: Test
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
  jobs:
  - job: DeployJob
    displayName: 'Check Deployment'
    steps:
    - script: make role deploy
      displayName: 'Check Deployment'
      env:
        ANSIBLE_HOST_KEY_CHECKING: false
```

### Jenkins

```groovy
// Jenkinsfile
pipeline {
    agent any
    
    environment {
        ANSIBLE_FORCE_COLOR = 'true'
        DOCKER_TLS_CERTDIR = ''
    }
    
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        
        stage('Install Dependencies') {
            steps {
                sh '''
                    pip install --upgrade pip
                    pip install ansible ansible-lint
                    ansible-galaxy collection install -r requirements.yml
                '''
            }
        }
        
        stage('Lint') {
            steps {
                sh 'make role lint'
            }
        }
        
        stage('Test') {
            parallel {
                stage('Test Minimal') {
                    steps {
                        sh 'make role test minimal'
                    }
                }
                stage('Test Default') {
                    steps {
                        sh 'make role test default'
                    }
                }
                stage('Test Performance') {
                    steps {
                        sh 'make role test performance'
                    }
                }
            }
        }
        
        stage('Deploy Check') {
            when {
                branch 'main'
            }
            steps {
                sh 'make role deploy'
            }
        }
    }
    
    post {
        always {
            archiveArtifacts artifacts: 'molecule/**/.molecule/**/*', allowEmptyArchive: true
        }
        
        success {
            echo 'Pipeline completed successfully!'
        }
        
        failure {
            echo 'Pipeline failed!'
        }
    }
}
```

### GitLab CI

```yaml
# .gitlab-ci.yml
stages:
  - lint
  - test
  - deploy

variables:
  ANSIBLE_FORCE_COLOR: "true"
  DOCKER_TLS_CERTDIR: ""

lint:
  stage: lint
  image: python:3.11
  before_script:
    - pip install ansible ansible-lint
    - ansible-galaxy collection install -r requirements.yml
  script:
    - make role lint

test:
  stage: test
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - apk add --no-cache make python3 py3-pip
    - pip install ansible ansible-lint
    - ansible-galaxy collection install -r requirements.yml
  script:
    - make role test $PRESET
  parallel:
    matrix:
      - PRESET: [minimal, default, performance]

deploy:
  stage: deploy
  image: python:3.11
  only:
    - main
  before_script:
    - pip install ansible ansible-lint
    - ansible-galaxy collection install -r requirements.yml
  script:
    - make role deploy
  variables:
    ANSIBLE_HOST_KEY_CHECKING: "false"
```

### Автоматическое тестирование новых ролей

**При создании новой роли в директории `roles/`:**
1. **Автоматически включается** в lint проверку
2. **Автоматически включается** в тестирование
3. **Автоматически включается** в развертывание
4. **CI/CD пайплайны** автоматически тестируют новую роль

**Настройка уведомлений:**
```yaml
# .github/workflows/ansible-test.yml
name: Ansible Testing
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: make role test
      - name: Notify on success
        if: success()
        run: echo "✅ All tests passed for new role"
      - name: Notify on failure
        if: failure()
        run: echo "❌ Tests failed for new role"
```

### Настройка автоматического тестирования новых ролей

**1. Автоматическое обнаружение новых ролей:**
```yaml
# .github/workflows/ansible-test.yml
name: Ansible Testing
on: [push, pull_request]

jobs:
  detect-roles:
    runs-on: ubuntu-latest
    outputs:
      roles: ${{ steps.detect.outputs.roles }}
    steps:
      - uses: actions/checkout@v4
      - name: Detect new roles
        id: detect
        run: |
          echo "roles=$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||' | tr '\n' ' ')" >> $GITHUB_OUTPUT

  test-roles:
    runs-on: ubuntu-latest
    needs: detect-roles
    strategy:
      matrix:
        role: ${{ fromJson(format('["{0}"]', needs.detect-roles.outputs.roles)) }}
    steps:
      - uses: actions/checkout@v4
      - name: Test role ${{ matrix.role }}
        run: |
          make role lint
          make role test
          echo "✅ Role ${{ matrix.role }} tested successfully"
```

**2. Автоматическое обновление playbook'ов:**
```bash
#!/bin/bash
# scripts/update-playbooks.sh
# Автоматическое обновление playbook'ов при добавлении новых ролей

echo "🔍 Обнаружение новых ролей..."

# Получаем список всех ролей
ROLES=$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||')

echo "📋 Найденные роли: $ROLES"

# Обновляем molecule/default/site.yml
echo "📝 Обновление molecule/default/site.yml..."
cat > molecule/default/site.yml << EOF
---
# Основной playbook для тестирования
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Тестирование всех ролей
  hosts: all
  roles:
EOF

for role in $ROLES; do
    echo "    - $role" >> molecule/default/site.yml
done

# Обновляем roles/deploy.yml
echo "📝 Обновление roles/deploy.yml..."
cat > roles/deploy.yml << EOF
---
# Playbook для развертывания на продакшн серверах
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Развертывание всех ролей
  hosts: all
  roles:
EOF

for role in $ROLES; do
    echo "    - $role" >> roles/deploy.yml
done

echo "✅ Playbook'и обновлены"
```

**3. Автоматическое тестирование в CI/CD:**
```yaml
# .github/workflows/ansible-test.yml
name: Ansible Testing
on: [push, pull_request]

jobs:
  update-playbooks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update playbooks
        run: |
          chmod +x scripts/update-playbooks.sh
          ./scripts/update-playbooks.sh
      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add molecule/default/site.yml roles/deploy.yml
          git diff --staged --quiet || git commit -m "Auto-update playbooks for new roles"
          git push

  test:
    runs-on: ubuntu-latest
    needs: update-playbooks
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: make role test
```

**4. Настройка уведомлений о новых ролях:**
```yaml
# .github/workflows/ansible-test.yml
name: Ansible Testing
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: make role test
      - name: Notify on success
        if: success()
        run: |
          echo "✅ All tests passed for new role"
          # Отправка уведомления в Slack/Teams
          curl -X POST -H 'Content-type: application/json' \
            --data '{"text":"✅ Ansible role tests passed"}' \
            ${{ secrets.SLACK_WEBHOOK_URL }}
      - name: Notify on failure
        if: failure()
        run: |
          echo "❌ Tests failed for new role"
          # Отправка уведомления в Slack/Teams
          curl -X POST -H 'Content-type: application/json' \
            --data '{"text":"❌ Ansible role tests failed"}' \
            ${{ secrets.SLACK_WEBHOOK_URL }}
```

**5. Автоматическое создание документации для новых ролей:**
```bash
#!/bin/bash
# scripts/generate-role-docs.sh
# Автоматическое создание документации для новых ролей

echo "📚 Генерация документации для ролей..."

# Получаем список всех ролей
ROLES=$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||')

for role in $ROLES; do
    echo "📝 Генерация документации для роли: $role"
    
    # Создаем README.md для роли если его нет
    if [ ! -f "roles/$role/README.md" ]; then
        cat > "roles/$role/README.md" << EOF
# Роль $role

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

## Описание

Роль для настройки и конфигурации $role сервиса.

## Требования

- Ansible >= 2.9
- Поддерживаемые ОС: Ubuntu, Debian, RHEL, CentOS, AlmaLinux, Rocky Linux

## Переменные

| Переменная | Тип | По умолчанию | Описание |
|------------|-----|--------------|----------|
| \`${role}_enabled\` | boolean | \`true\` | Включить роль |
| \`${role}_packages\` | list | \`[]\` | Пакеты для установки |

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

\`\`\`yaml
- name: Настройка $role
  hosts: all
  roles:
    - $role
\`\`\`

## Tags

- \`$role\` - выполнение всех задач роли
- \`install\` - установка пакетов
- \`config\` - настройка конфигурации
EOF
    fi
done

echo "✅ Документация сгенерирована"
```

**6. Автоматическое тестирование новых ролей в CI/CD:**
   ```yaml
# .github/workflows/ansible-test.yml
name: Ansible Testing
on: [push, pull_request]

jobs:
  detect-roles:
    runs-on: ubuntu-latest
    outputs:
      roles: ${{ steps.detect.outputs.roles }}
    steps:
      - uses: actions/checkout@v4
      - name: Detect new roles
        id: detect
        run: |
          echo "roles=$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||' | tr '\n' ' ')" >> $GITHUB_OUTPUT

  update-playbooks:
    runs-on: ubuntu-latest
    needs: detect-roles
    steps:
      - uses: actions/checkout@v4
      - name: Update playbooks
        run: |
          chmod +x scripts/update-playbooks.sh
          ./scripts/update-playbooks.sh
      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add molecule/default/site.yml roles/deploy.yml
          git diff --staged --quiet || git commit -m "Auto-update playbooks for new roles"
          git push

  lint:
    runs-on: ubuntu-latest
    needs: update-playbooks
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install ansible ansible-lint
          ansible-galaxy collection install -r requirements.yml
      - name: Run lint
        run: make role lint

  test:
    runs-on: ubuntu-latest
    needs: [update-playbooks, lint]
    strategy:
      matrix:
        preset: [minimal, default, performance]
    steps:
      - uses: actions/checkout@v4
      - name: Setup Docker
        run: |
          sudo systemctl start docker
          sudo usermod -aG docker $USER
      - name: Run tests
        run: make role test ${{ matrix.preset }}

  deploy-check:
    runs-on: ubuntu-latest
    needs: [lint, test]
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Check deployment
        run: make role deploy
        env:
          ANSIBLE_HOST_KEY_CHECKING: false

  notify:
    runs-on: ubuntu-latest
    needs: [lint, test, deploy-check]
    if: always()
    steps:
      - name: Notify on success
        if: needs.lint.result == 'success' && needs.test.result == 'success'
        run: |
          echo "✅ All tests passed for new roles"
          curl -X POST -H 'Content-type: application/json' \
            --data '{"text":"✅ Ansible role tests passed for new roles"}' \
            ${{ secrets.SLACK_WEBHOOK_URL }}
      - name: Notify on failure
        if: needs.lint.result == 'failure' || needs.test.result == 'failure'
        run: |
          echo "❌ Tests failed for new roles"
          curl -X POST -H 'Content-type: application/json' \
            --data '{"text":"❌ Ansible role tests failed for new roles"}' \
            ${{ secrets.SLACK_WEBHOOK_URL }}
```

**7. Автоматическое создание скриптов:**
```bash
#!/bin/bash
# scripts/create-role-scripts.sh
# Автоматическое создание скриптов для новых ролей

echo "🔧 Создание скриптов для новых ролей..."

# Создаем директорию scripts если её нет
mkdir -p scripts

# Создаем скрипт для обновления playbook'ов
cat > scripts/update-playbooks.sh << 'EOF'
#!/bin/bash
# Автоматическое обновление playbook'ов при добавлении новых ролей

echo "🔍 Обнаружение новых ролей..."

# Получаем список всех ролей
ROLES=$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||')

echo "📋 Найденные роли: $ROLES"

# Обновляем molecule/default/site.yml
echo "📝 Обновление molecule/default/site.yml..."
cat > molecule/default/site.yml << EOL
---
# Основной playbook для тестирования
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Тестирование всех ролей
  hosts: all
  roles:
EOL

for role in $ROLES; do
    echo "    - $role" >> molecule/default/site.yml
done

# Обновляем roles/deploy.yml
echo "📝 Обновление roles/deploy.yml..."
cat > roles/deploy.yml << EOL
---
# Playbook для развертывания на продакшн серверах
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Развертывание всех ролей
  hosts: all
  roles:
EOL

for role in $ROLES; do
    echo "    - $role" >> roles/deploy.yml
done

echo "✅ Playbook'и обновлены"
EOF

# Создаем скрипт для генерации документации
cat > scripts/generate-role-docs.sh << 'EOF'
#!/bin/bash
# Автоматическое создание документации для новых ролей

echo "📚 Генерация документации для ролей..."

# Получаем список всех ролей
ROLES=$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||')

for role in $ROLES; do
    echo "📝 Генерация документации для роли: $role"
    
    # Создаем README.md для роли если его нет
    if [ ! -f "roles/$role/README.md" ]; then
        cat > "roles/$role/README.md" << EOL
# Роль $role

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

## Описание

Роль для настройки и конфигурации $role сервиса.

## Требования

- Ansible >= 2.9
- Поддерживаемые ОС: Ubuntu, Debian, RHEL, CentOS, AlmaLinux, Rocky Linux

## Переменные

| Переменная | Тип | По умолчанию | Описание |
|------------|-----|--------------|----------|
| \`${role}_enabled\` | boolean | \`true\` | Включить роль |
| \`${role}_packages\` | list | \`[]\` | Пакеты для установки |

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

\`\`\`yaml
- name: Настройка $role
  hosts: all
  roles:
    - $role
\`\`\`

## Tags

- \`$role\` - выполнение всех задач роли
- \`install\` - установка пакетов
- \`config\` - настройка конфигурации
EOL
    fi
done

echo "✅ Документация сгенерирована"
EOF

# Делаем скрипты исполняемыми
chmod +x scripts/update-playbooks.sh
chmod +x scripts/generate-role-docs.sh

echo "✅ Скрипты созданы"
```

## 📊 Мониторинг и диагностика

> 📖 **Подробное руководство:** [docs/monitoring.md](docs/monitoring.md)

### Диагностика Docker

```bash
# Диагностика buildx проблем
make docker diagnose

# Проверка builder'а
make docker setup-builder

# Сброс builder'а при проблемах
make docker reset-builder
```

### Логи и отчеты

```bash
# Просмотр логов контейнера
docker logs ansible-controller

# Вход в контейнер для отладки
docker exec -it ansible-controller bash
```

## 🛠️ Разработка

> 📖 **Подробное руководство:** [docs/creating-roles.md](docs/creating-roles.md)

### Создание новых preset'ов

1. Создайте файл `molecule/presets/my-preset.yml`:

```yaml
#description: Мой кастомный preset
docker_network: labnet
generated_inventory: "{{ molecule_ephemeral_directory }}/inventory/hosts.ini"

images:
  ubuntu: "inecs/ansible-lab:ubuntu-latest"
  rhel: "inecs/ansible-lab:rhel-latest"

hosts:
  - name: web1
    family: ubuntu
    groups: [web, frontend]
  - name: db1
    family: rhel
    groups: [database, backend]
```

2. Используйте preset:

```bash
make role test my-preset
```

### Создание новых ролей

#### 1. Создание структуры роли

```bash
# Создание директории роли
mkdir -p roles/my-role/{tasks,handlers,templates,files,vars,defaults,meta}

# Создание основных файлов
touch roles/my-role/{tasks,handlers,meta}/main.yml
touch roles/my-role/defaults/main.yml
touch roles/my-role/vars/main.yml
touch roles/my-role/README.md
```

#### 2. Структура файлов роли

**`roles/my-role/tasks/main.yml`** - основные задачи:
```yaml
---
# Основные задачи для роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Установка пакетов
  package:
    name: "{{ my_role_packages }}"
    state: present
  when: my_role_install_packages | default(true)
  tags:
    - my-role
    - install

- name: Настройка конфигурации
  template:
    src: my-role.conf.j2
    dest: /etc/my-role/my-role.conf
    owner: root
    group: root
    mode: '0644'
  notify: restart my-role
  tags:
    - my-role
    - config
```

**`roles/my-role/defaults/main.yml`** - переменные по умолчанию:
```yaml
---
# Переменные по умолчанию для роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

# Основные настройки
my_role_enabled: true
my_role_install_packages: true
my_role_packages:
  - nginx
  - curl

# Конфигурация
my_role_config_file: /etc/my-role/my-role.conf
my_role_log_level: info
```

**`roles/my-role/handlers/main.yml`** - обработчики:
```yaml
---
# Обработчики для роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: restart my-role
  service:
    name: "{{ my_role_service_name | default('my-role') }}"
    state: restarted
  when: my_role_enabled | default(true)
```

**`roles/my-role/meta/main.yml`** - метаданные роли:
```yaml
---
# Метаданные роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

galaxy_info:
  author: Сергей Антропов
  description: Моя кастомная роль для AnsibleTemplate
  company: https://devops.org.ru
  license: MIT
  min_ansible_version: "2.9"
  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: Debian
      versions:
        - bullseye
        - bookworm
    - name: EL
      versions:
        - 7
        - 8
        - 9
  galaxy_tags:
    - system
    - configuration
    - my-role

dependencies: []
```

**`roles/my-role/README.md`** - документация роли:
```markdown
# Роль My-Role

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

## Описание

Роль для настройки и конфигурации my-role сервиса.

## Требования

- Ansible >= 2.9
- Поддерживаемые ОС: Ubuntu, Debian, RHEL, CentOS, AlmaLinux, Rocky Linux

## Переменные

| Переменная | Тип | По умолчанию | Описание |
|------------|-----|--------------|----------|
| `my_role_enabled` | boolean | `true` | Включить роль |
| `my_role_packages` | list | `['nginx', 'curl']` | Пакеты для установки |
| `my_role_log_level` | string | `info` | Уровень логирования |

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

```yaml
- name: Настройка my-role
  hosts: all
  roles:
    - my-role
```

## Tags

- `my-role` - выполнение всех задач роли
- `install` - установка пакетов
- `config` - настройка конфигурации
```

#### 3. Регистрация роли для проверок

**Автоматическая регистрация:** Роль автоматически будет проверена при выполнении:
```bash
# Lint проверка всех ролей в директории roles/
make role lint

# Тестирование всех ролей
make role test
```

**Как это работает:**
1. **Lint проверка:** `ansible-lint roles/` автоматически находит все роли в директории `roles/`
2. **Тестирование:** `molecule/default/site.yml` автоматически включает все роли из `roles/`
3. **Развертывание:** `roles/deploy.yml` автоматически включает все роли из `roles/`

**Ручная проверка конкретной роли:**
```bash
# Lint проверка конкретной роли
ansible-lint roles/my-role/

# Тестирование конкретной роли
cd roles/my-role
molecule test
```

**Автоматическое включение ролей в playbook'и:**

**В `molecule/default/site.yml` (для тестирования):**
```yaml
---
# Автоматически включает все роли из директории roles/
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Тестирование всех ролей
  hosts: all
  roles:
    - ping          # Автоматически включается
    - my-role       # Автоматически включается
    # Добавьте сюда новые роли по мере их создания
```

**В `roles/deploy.yml` (для продакшн развертывания):**
```yaml
---
# Автоматически включает все роли из директории roles/
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Развертывание всех ролей
  hosts: all
  roles:
    - ping          # Автоматически включается
    - my-role       # Автоматически включается
    # Добавьте сюда новые роли по мере их создания
```

#### 4. Интеграция с основным playbook

**Обновление `molecule/default/site.yml`:**
```yaml
---
# Основной playbook для тестирования
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Тестирование роли ping
  hosts: all
  roles:
    - ping

- name: Тестирование роли my-role
  hosts: all
  roles:
    - my-role
vars:
    my_role_enabled: true
    my_role_packages:
      - nginx
      - curl
```

**Обновление `roles/deploy.yml`:**
```yaml
---
# Playbook для развертывания на продакшн серверах
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Развертывание роли ping
  hosts: all
  roles:
    - ping

- name: Развертывание роли my-role
  hosts: all
  roles:
    - my-role
  vars:
    my_role_enabled: true
    my_role_packages:
      - nginx
      - curl
```

#### 5. Настройка переменных для разных окружений

**Переменные для тестирования (в preset файлах):**
```yaml
# molecule/presets/my-custom-preset.yml
---
#description: Кастомный preset для тестирования my-role
  docker_network: labnet
  generated_inventory: "{{ molecule_ephemeral_directory }}/inventory/hosts.ini"

# Переменные для тестирования
my_role_enabled: true
my_role_packages:
  - nginx
  - curl
my_role_log_level: debug
my_role_test_mode: true

hosts:
  - name: u1
    family: debian
    groups: [test]
```

**Переменные для продакшн (в group_vars):**
```yaml
# inventory/group_vars/all.yml
---
# Общие переменные для всех серверов
my_role_enabled: true
my_role_packages:
  - nginx
  - curl
  - htop
my_role_log_level: info
my_role_test_mode: false

# Продакшн настройки
my_role_production: true
my_role_backup_enabled: true
```

**Переменные для конкретных групп:**
```yaml
# inventory/group_vars/web_servers.yml
---
# Переменные для web серверов
my_role_web_config: true
my_role_nginx_config: |
  server {
      listen 80;
      server_name example.com;
      location / {
          proxy_pass http://backend;
      }
  }
```

**Переменные для конкретных хостов:**
```yaml
# inventory/host_vars/web1.example.com.yml
---
# Переменные для конкретного хоста
my_role_hostname: web1
my_role_domain: example.com
my_role_ssl_enabled: true
```

#### 6. Тестирование новой роли

```bash
# 1. Lint проверка
make role lint

# 2. Тестирование с default preset
make role test

# 3. Тестирование с custom preset
make role test my-custom-preset

# 4. Тестирование на реальных серверах (dry-run)
make role deploy
```

#### 7. Полный цикл разработки роли

```bash
# 1. Создание роли
mkdir -p roles/my-role/{tasks,handlers,templates,files,vars,defaults,meta}
touch roles/my-role/{tasks,handlers,meta}/main.yml
touch roles/my-role/defaults/main.yml
touch roles/my-role/vars/main.yml
touch roles/my-role/README.md

# 2. Разработка роли
# ... редактирование файлов роли ...

# 3. Lint проверка
make role lint

# 4. Тестирование в Docker
make role test minimal

# 5. Тестирование с custom preset
make role test my-custom-preset

# 6. Тестирование на реальных серверах (dry-run)
make role deploy

# 7. Развертывание на продакшн
make role deploy
# Подтвердить развертывание: y
```

#### 8. Автоматическое обновление playbook'ов

**Добавьте в Makefile команду для автоматического обновления:**
```makefile
# Автоматическое обновление playbook'ов
update-playbooks:
	@echo "🔍 Обнаружение новых ролей..."
	@ROLES=$$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||' | tr '\n' ' '); \
	echo "📋 Найденные роли: $$ROLES"; \
	echo "📝 Обновление molecule/default/site.yml..."; \
	echo "---" > molecule/default/site.yml; \
	echo "# Основной playbook для тестирования" >> molecule/default/site.yml; \
	echo "# Автор: Сергей Антропов" >> molecule/default/site.yml; \
	echo "# Сайт: https://devops.org.ru" >> molecule/default/site.yml; \
	echo "" >> molecule/default/site.yml; \
	echo "- name: Тестирование всех ролей" >> molecule/default/site.yml; \
	echo "  hosts: all" >> molecule/default/site.yml; \
	echo "  roles:" >> molecule/default/site.yml; \
	for role in $$ROLES; do \
		echo "    - $$role" >> molecule/default/site.yml; \
	done; \
	echo "📝 Обновление roles/deploy.yml..."; \
	echo "---" > roles/deploy.yml; \
	echo "# Playbook для развертывания на продакшн серверах" >> roles/deploy.yml; \
	echo "# Автор: Сергей Антропов" >> roles/deploy.yml; \
	echo "# Сайт: https://devops.org.ru" >> roles/deploy.yml; \
	echo "" >> roles/deploy.yml; \
	echo "- name: Развертывание всех ролей" >> roles/deploy.yml; \
	echo "  hosts: all" >> roles/deploy.yml; \
	echo "  roles:" >> roles/deploy.yml; \
	for role in $$ROLES; do \
		echo "    - $$role" >> roles/deploy.yml; \
	done; \
	echo "✅ Playbook'и обновлены"
```

**Использование:**
```bash
# Автоматическое обновление playbook'ов
make update-playbooks

# Проверка обновленных playbook'ов
make role test
```

#### 9. Автоматическое создание документации

**Добавьте в Makefile команду для создания документации:**
```makefile
# Автоматическое создание документации для ролей
generate-docs:
	@echo "📚 Генерация документации для ролей..."
	@ROLES=$$(find roles/ -name 'main.yml' -path '*/tasks/*' | sed 's|roles/||; s|/tasks/main.yml||'); \
	for role in $$ROLES; do \
		echo "📝 Генерация документации для роли: $$role"; \
		if [ ! -f "roles/$$role/README.md" ]; then \
			echo "# Роль $$role" > "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "**Автор:** Сергей Антропов" >> "roles/$$role/README.md"; \
			echo "**Сайт:** https://devops.org.ru" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "## Описание" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "Роль для настройки и конфигурации $$role сервиса." >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "## Требования" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "- Ansible >= 2.9" >> "roles/$$role/README.md"; \
			echo "- Поддерживаемые ОС: Ubuntu, Debian, RHEL, CentOS, AlmaLinux, Rocky Linux" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "## Переменные" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "| Переменная | Тип | По умолчанию | Описание |" >> "roles/$$role/README.md"; \
			echo "|------------|-----|--------------|----------|" >> "roles/$$role/README.md"; \
			echo "| \`$${role}_enabled\` | boolean | \`true\` | Включить роль |" >> "roles/$$role/README.md"; \
			echo "| \`$${role}_packages\` | list | \`[]\` | Пакеты для установки |" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "## Примеры использования" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "\`\`\`yaml" >> "roles/$$role/README.md"; \
			echo "- name: Настройка $$role" >> "roles/$$role/README.md"; \
			echo "  hosts: all" >> "roles/$$role/README.md"; \
			echo "  roles:" >> "roles/$$role/README.md"; \
			echo "    - $$role" >> "roles/$$role/README.md"; \
			echo "\`\`\`" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "## Tags" >> "roles/$$role/README.md"; \
			echo "" >> "roles/$$role/README.md"; \
			echo "- \`$$role\` - выполнение всех задач роли" >> "roles/$$role/README.md"; \
			echo "- \`install\` - установка пакетов" >> "roles/$$role/README.md"; \
			echo "- \`config\` - настройка конфигурации" >> "roles/$$role/README.md"; \
		fi; \
	done; \
	echo "✅ Документация сгенерирована"
```

**Использование:**
```bash
# Автоматическое создание документации
make generate-docs

# Проверка созданной документации
ls -la roles/*/README.md
```

#### 10. Полный цикл с автоматизацией

```bash
# 1. Создание роли
mkdir -p roles/my-role/{tasks,handlers,templates,files,vars,defaults,meta}
touch roles/my-role/{tasks,handlers,meta}/main.yml
touch roles/my-role/defaults/main.yml
touch roles/my-role/vars/main.yml

# 2. Автоматическое создание документации
make generate-docs

# 3. Автоматическое обновление playbook'ов
make update-playbooks

# 4. Lint проверка
make role lint

# 5. Тестирование в Docker
make role test minimal

# 6. Тестирование с custom preset
make role test my-custom-preset

# 7. Тестирование на реальных серверах (dry-run)
make role deploy

# 8. Развертывание на продакшн
make role deploy
# Подтвердить развертывание: y
```

## 🔧 Конфигурация

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

Скопируйте `env.example` в `.env` и настройте:

```bash
# Основные настройки
PROJECT_NAME=ansible-template
VERSION=2.0.0
AUTHOR="Сергей Антропов"
SITE="https://devops.org.ru"

# Docker настройки
DOCKER_IMAGE=inecs/ansible-lab:ansible-controller-latest
DOCKER_REGISTRY=inecs/ansible-lab
DOCKER_VERSION=latest

# Multi-arch настройки
DOCKER_PLATFORMS=linux/amd64,linux/arm64
DOCKER_BUILDX_BUILDER=multiarch-builder
```

### Ansible конфигурация

```ini
# ansible.cfg
[defaults]
inventory = inventory/hosts.ini
remote_user = devops
host_key_checking = False
enable_plugins = yaml, ini
roles_path = roles/
interpreter_python = auto

# Настройки для тестирования
[test]
inventory = molecule/default/inventory/hosts.ini
remote_user = ansible
host_key_checking = False

# Настройки для продакшн
[production]
inventory = inventory/hosts.ini
remote_user = devops
host_key_checking = False
```

### Настройка переменных для разных окружений

**Структура переменных:**
```
inventory/
├── hosts.ini                    # Основной инвентори
├── group_vars/                  # Переменные для групп
│   ├── all.yml                 # Общие переменные
│   ├── web_servers.yml         # Переменные для web серверов
│   ├── db_servers.yml          # Переменные для db серверов
│   └── monitoring.yml          # Переменные для мониторинга
├── host_vars/                   # Переменные для конкретных хостов
│   ├── web1.example.com.yml    # Переменные для web1
│   ├── web2.example.com.yml    # Переменные для web2
│   └── db1.example.com.yml     # Переменные для db1
└── vault/                      # Зашифрованные переменные
    ├── secrets.yml            # Секреты
    └── passwords.yml           # Пароли
```

**Примеры переменных:**

**`inventory/group_vars/all.yml`** - общие переменные:
```yaml
---
# Общие переменные для всех серверов
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

# Основные настройки
ansible_user: devops
ansible_ssh_private_key_file: ~/.ssh/id_rsa
ansible_ssh_common_args: '-o StrictHostKeyChecking=no'

# Переменные для ролей
ping_host: yandex.ru
ping_count: 5

# Продакшн настройки
production_mode: true
backup_enabled: true
monitoring_enabled: true
```

**`inventory/group_vars/web_servers.yml`** - переменные для web серверов:
```yaml
---
# Переменные для web серверов
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

# Web настройки
nginx_enabled: true
nginx_ssl_enabled: true
nginx_domains:
  - example.com
  - www.example.com

# Переменные для ролей
my_role_web_config: true
my_role_nginx_config: |
  server {
      listen 80;
      server_name example.com;
      location / {
          proxy_pass http://backend;
      }
  }
```

**`inventory/host_vars/web1.example.com.yml`** - переменные для конкретного хоста:
```yaml
---
# Переменные для web1.example.com
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

# Хост-специфичные настройки
hostname: web1
domain: example.com
ssl_certificate: /etc/ssl/certs/web1.crt
ssl_private_key: /etc/ssl/private/web1.key

# Переменные для ролей
my_role_hostname: web1
my_role_domain: example.com
my_role_ssl_enabled: true
```

**`inventory/vault/secrets.yml`** - зашифрованные секреты:
```yaml
---
# Зашифрованные секреты
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

# Секреты для ролей
my_role_api_key: "{{ vault_my_role_api_key }}"
my_role_database_password: "{{ vault_my_role_database_password }}"
my_role_ssl_certificate: "{{ vault_my_role_ssl_certificate }}"
```

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

**В `roles/my-role/tasks/main.yml`:**
```yaml
---
# Основные задачи для роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: Установка пакетов
  package:
    name: "{{ my_role_packages }}"
    state: present
  when: my_role_enabled | default(true)
  tags:
    - my-role
    - install

- name: Настройка конфигурации
  template:
    src: my-role.conf.j2
    dest: "{{ my_role_config_file | default('/etc/my-role/my-role.conf') }}"
    owner: root
    group: root
    mode: '0644'
  notify: restart my-role
  tags:
    - my-role
    - config

- name: Настройка SSL сертификата
  copy:
    content: "{{ my_role_ssl_certificate }}"
    dest: /etc/ssl/certs/my-role.crt
    owner: root
    group: root
    mode: '0644'
  when: my_role_ssl_enabled | default(false)
  tags:
    - my-role
    - ssl
```

**В `roles/my-role/templates/my-role.conf.j2`:**
```jinja2
# Конфигурация my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

[main]
enabled = {{ my_role_enabled | default(true) }}
log_level = {{ my_role_log_level | default('info') }}
hostname = {{ my_role_hostname | default(ansible_hostname) }}
domain = {{ my_role_domain | default('localhost') }}

{% if my_role_ssl_enabled | default(false) %}
[ssl]
enabled = true
certificate = /etc/ssl/certs/my-role.crt
private_key = /etc/ssl/private/my-role.key
{% endif %}

{% if my_role_web_config | default(false) %}
[web]
enabled = true
{% raw %}
{{ my_role_nginx_config }}
{% endraw %}
{% endif %}
```

## 🐛 Troubleshooting

### Проблемы с Docker

1. **Builder не создается:**
   ```bash
   make docker diagnose
   make docker reset-builder
   ```

2. **Образы не собираются:**
   ```bash
   make docker clean
   make docker setup-builder
   make docker build
   ```

3. **Проблемы с multi-arch:**
   ```bash
   make docker clean-builder
   make docker setup-builder
   ```

### Проблемы с тестированием

1. **Preset не найден:**
   ```bash
   make presets list
   # Проверьте наличие файла molecule/presets/your-preset.yml
   ```

2. **Контейнеры не создаются:**
   ```bash
   make docker clean
   make role test
   ```

3. **Проблемы с systemd:**
   ```bash
   # Проверьте, что образы поддерживают systemd
   make custom-images check
   ```

## 📈 Производительность

### Оптимизация сборки

```bash
# Использование кеша Docker
make docker build

# Очистка кеша при проблемах
make docker rebuild
```

### Оптимизация тестирования

```bash
# Использование minimal preset для быстрого тестирования
make role test minimal

# Использование performance preset для нагрузочного тестирования
make role test performance
```

## 🤝 Вклад в проект

1. Fork репозитория
2. Создайте feature branch (`git checkout -b feature/amazing-feature`)
3. Commit изменения (`git commit -m 'Add amazing feature'`)
4. Push в branch (`git push origin feature/amazing-feature`)
5. Создайте Pull Request

## 📄 Лицензия

MIT License - см. файл [LICENSE](LICENSE)

## 📞 Поддержка

При возникновении проблем:

1. Проверьте наличие Docker и Docker Compose
2. Убедитесь, что все preset файлы существуют
3. Используйте `make help` для справки
4. Проверьте логи: `make docker shell` и `docker logs ansible-controller`
5. Выполните диагностику: `make docker diagnose`

## 🎯 Результат

Система тестирования теперь работает корректно:

1. ✅ **Полностью универсальная система preset'ов - любой preset без изменения Makefile**
2. ✅ **Multi-arch поддержка для всех образов (amd64, arm64, riscv64, ppc64le, s390x, 386, arm/v7, arm/v6)**
3. ✅ **Динамическое определение preset'ов через `filter-out` и `cut`**
4. ✅ **Проверка существования preset'ов с подробной справкой**
5. ✅ **Унифицированные имена контейнеров**
6. ✅ **Надежные fallback значения**
7. ✅ **Поддержка неограниченного количества custom preset'ов**
8. ✅ **Автономная preset система сама управляет контейнерами**
9. ✅ **Подробная документация и справка**
10. ✅ **CI/CD интеграция с GitHub Actions, Azure DevOps, Jenkins, GitLab CI**
11. ✅ **Ansible Vault интеграция с автоматическим управлением секретами**
12. ✅ **Собственные Docker образы для различных ОС**
13. ✅ **Systemd поддержка в контейнерах**
14. ✅ **DinD/DOoD поддержка для Docker функциональности**
15. ✅ **Интерактивное управление ролями** - создание, удаление, просмотр ролей
16. ✅ **Автоматическое обновление playbook'ов** при добавлении новых ролей
17. ✅ **Комплексное тестирование всех образов** одновременно (all-images preset)
18. ✅ **Подробная документация по кастомизации deploy.yml** с примерами

## 📚 Навигация по документации

### 🚀 Для начинающих
1. **[docs/getting-started.md](docs/getting-started.md)** - Установка и первое тестирование
2. **[dockerfiles/README.md](dockerfiles/README.md)** - Изучение Docker образов
3. **[docs/creating-roles.md](docs/creating-roles.md)** - Создание первой роли

### 🛠️ Для разработчиков
1. **[docs/creating-roles.md](docs/creating-roles.md)** - Полное руководство по созданию ролей
2. **[docs/cicd-setup.md](docs/cicd-setup.md)** - Настройка CI/CD
3. **[docs/monitoring.md](docs/monitoring.md)** - Мониторинг и диагностика

### 🏗️ Для DevOps
1. **[docs/cicd-setup.md](docs/cicd-setup.md)** - Настройка CI/CD для всех платформ
2. **[docs/monitoring.md](docs/monitoring.md)** - Мониторинг и troubleshooting
3. **[dockerfiles/README.md](dockerfiles/README.md)** - Управление Docker образами

### 📖 Дополнительные ресурсы
- **Makefile** - Все доступные команды
- **ansible.cfg** - Конфигурация Ansible
- **requirements.yml** - Ansible коллекции
- **molecule/presets/** - Готовые preset'ы для тестирования

---

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