# Ansible Template - Универсальная лаборатория для тестирования Ansible ролей

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ansible](https://img.shields.io/badge/Ansible-2.15+-blue.svg)](https://www.ansible.com/)
[![Molecule](https://img.shields.io/badge/Molecule-5.0+-green.svg)](https://molecule.readthedocs.io/)
[![Docker](https://img.shields.io/badge/Docker-20.0+-blue.svg)](https://www.docker.com/)

## 📋 Описание

**Ansible Template** - это универсальная лаборатория для тестирования Ansible ролей в различных конфигурациях. Проект предоставляет гибкую и мощную среду для тестирования Ansible ролей, включая Docker-in-Docker (DinD), Docker-outside-of-Docker (DOoD), кластеры Kubernetes (Kind), Istio, Kiali, Prometheus и Grafana.

### 🎯 Основные возможности

- **Динамическое создание инфраструктуры** - автоматическое развертывание Docker контейнеров и Kind кластеров
- **Поддержка различных ОС** - тестирование ролей на Debian и RHEL-подобных системах
- **Docker-in-Docker (DinD)** - изолированные Docker-среды внутри контейнеров
- **Docker-outside-of-Docker (DOoD)** - использование Docker-демона хоста из контейнера
- **Kubernetes кластеры** - полноценные Kind кластеры с аддонами
- **Service Mesh** - Istio с Kiali для визуализации
- **Мониторинг** - Prometheus, Grafana, Jaeger для полной наблюдаемости
- **21 готовый пресет** - от простых до экстремально сложных сценариев
- **HTML отчеты** - красивые отчеты о результатах тестирования
- **Снапшоты** - сохранение и восстановление состояния лаборатории

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

### Предварительные требования

- Docker 20.0+
- Docker Compose 2.0+
- Make
- Git

### Установка

```bash
# Клонировать репозиторий
git clone https://github.com/your-username/ansible-template.git
cd ansible-template

# Создать необходимые файлы
echo "your-vault-password" > vault-password.txt
mkdir -p roles
mkdir -p files/playbooks

# Установить pre-commit хуки (опционально)
make pre-commit-install
```

### Первый запуск

```bash
# Инициализация проекта
make init

# Поднять контроллер
make lab up

# Запустить минимальную лабораторию
make lab test

# Посмотреть отчет
make report
```

### Основные команды

```bash
# Показать справку
make help

# Управление лабораторией
make lab up          # Поднять контроллер
make lab down        # Остановить контроллер
make lab test        # Полный цикл тестирования
make lab create      # Создать инфраструктуру
make lab converge    # Запустить роли
make lab verify      # Проверить работу
make lab destroy     # Уничтожить инфраструктуру
make lab reset       # Полный сброс

# Управление Kubernetes
make kube sh         # Войти в контейнер
make kube cmd CLUSTER=lab CMD="get pods -A"
make kube kiali CLUSTER=lab
make kube istio CLUSTER=lab
make kube grafana CLUSTER=lab
make kube prom CLUSTER=lab
make kube kubeconfig CLUSTER=lab  # Получить kubeconfig

# Управление пресетами
make preset list     # Список пресетов
make preset create NAME=my-preset
make preset test NAME=my-preset
make preset edit NAME=my-preset

# Управление ролями
make role list       # Список ролей
make role create NAME=my-role  # Создать роль (интерактивно)
make role test NAME=my-role    # Тестировать роль
make role lint       # Проверка ролей
make role deploy     # Развертывание ролей
make role info NAME=my-role    # Информация о роли
make role playbook NAME=my-role  # Управление playbooks роли

# Проверка всего проекта
make lint            # Проверить весь проект на ошибки
make check-secrets   # Проверить безопасность секретов
make idempotence     # Проверить идемпотентность
make chaos           # Запустить Chaos Engineering тесты

# Управление Vault
make vault show      # Показать содержимое
make vault create    # Создать vault файл
make vault edit      # Редактировать vault файл

# Управление Git
make git status      # Статус репозитория
make git add         # Добавить файлы
make git commit MESSAGE="your message"
make git push        # Отправить изменения

# Отчеты и мониторинг
make report          # HTML отчет
make kubeconfigs     # Получить все kubeconfig файлы
make open-report     # Открыть отчет в браузере
make full-test       # Полный цикл с отчетом и kubeconfig
make snapshot        # Создать снапшот
make restore         # Восстановить снапшот
make cleanup         # Очистить лабораторию
```

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

### Основные разделы

- **[Универсальная лаборатория](docs/universal-lab.md)** - полное руководство по работе с лабораторией
- **[Пресеты](docs/presets.md)** - описание всех 21 готового пресета
- **[Роли](docs/roles.md)** - структура и создание Ansible ролей
- **[CI/CD](ci-cd/README.md)** - настройка CI/CD для Ansible ролей

### Дополнительные материалы

- **[Примеры использования](docs/examples.md)** - практические примеры
- **[Troubleshooting](docs/troubleshooting.md)** - решение проблем
- **[API Reference](docs/api.md)** - справочник по API

## 🎛️ Пресеты

### Классические пресеты (systemd контейнеры)

| Пресет | Машины | Описание | Команда |
|--------|--------|----------|---------|
| `minimal.yml` | 1-3 | Базовая конфигурация | `make lab-test LAB_SPEC=molecule/presets/minimal.yml` |
| `webapp.yml` | 3-5 | Веб-приложение | `make lab-test LAB_SPEC=molecule/presets/webapp.yml` |
| `microservices.yml` | 5-8 | Микросервисы | `make lab-test LAB_SPEC=molecule/presets/microservices.yml` |
| `ha.yml` | 6-10 | Высокая доступность | `make lab-test LAB_SPEC=molecule/presets/ha.yml` |
| `k8s-cluster.yml` | 8-12 | Kubernetes кластер | `make lab-test LAB_SPEC=molecule/presets/k8s-cluster.yml` |
| `cicd.yml` | 10-15 | CI/CD пайплайн | `make lab-test LAB_SPEC=molecule/presets/cicd.yml` |
| `bigdata.yml` | 12-18 | Big Data кластер | `make lab-test LAB_SPEC=molecule/presets/bigdata.yml` |
| `servicemesh.yml` | 15-20 | Service Mesh | `make lab-test LAB_SPEC=molecule/presets/servicemesh.yml` |
| `enterprise.yml` | 18-20 | Enterprise | `make lab-test LAB_SPEC=molecule/presets/enterprise.yml` |
| `maximum.yml` | 20 | Максимальный | `make lab-test LAB_SPEC=molecule/presets/maximum.yml` |

### Kubernetes пресеты

| Пресет | Описание | Команда |
|--------|----------|---------|
| `k8s-single.yml` | Одиночный Kind кластер | `make lab-test LAB_SPEC=molecule/presets/k8s-single.yml` |
| `k8s-multi.yml` | Мульти-кластер (dev/staging/prod) | `make lab-test LAB_SPEC=molecule/presets/k8s-multi.yml` |
| `k8s-istio-full.yml` | Полный стек Istio | `make lab-test LAB_SPEC=molecule/presets/k8s-istio-full.yml` |

### Docker пресеты

| Пресет | Тип | Описание | Команда |
|--------|-----|----------|---------|
| `dind-simple.yml` | DinD | 3 изолированных Docker среды | `make lab-test LAB_SPEC=molecule/presets/dind-simple.yml` |
| `dind-swarm.yml` | DinD | Docker Swarm кластер | `make lab-test LAB_SPEC=molecule/presets/dind-swarm.yml` |
| `dind-compose.yml` | DinD | Docker Compose стеки | `make lab-test LAB_SPEC=molecule/presets/dind-compose.yml` |
| `dood-simple.yml` | DOoD | 3 DOoD контейнера | `make lab-test LAB_SPEC=molecule/presets/dood-simple.yml` |
| `dood-mixed.yml` | DOoD | Смешанная конфигурация | `make lab-test LAB_SPEC=molecule/presets/dood-mixed.yml` |

### Смешанные пресеты

| Пресет | Описание | Команда |
|--------|----------|---------|
| `mixed-k8s-dind.yml` | Kubernetes + DinD | `make lab-test LAB_SPEC=molecule/presets/mixed-k8s-dind.yml` |
| `mixed-k8s-dood.yml` | Kubernetes + DOoD | `make lab-test LAB_SPEC=molecule/presets/mixed-k8s-dood.yml` |
| `mixed-full.yml` | Полная гибридная конфигурация | `make lab-test LAB_SPEC=molecule/presets/mixed-full.yml` |

## 🛠️ Основные команды

### Управление лабораторией

```bash
# Поднять контроллер
make lab-up

# Погасить контроллер
make lab-down

# Полный цикл тестирования
make lab-test

# Создать инфраструктуру
make lab-create

# Запустить роли
make lab-converge

# Проверить работу
make lab-verify

# Уничтожить инфраструктуру
make lab-destroy

# Полный сброс
make lab-reset
```

### Снапшоты и восстановление

```bash
# Сохранить снапшот
make lab-snapshot

# Восстановить из снапшота
make lab-restore

# Очистить лабораторию
make lab-cleanup
```

### Kubernetes команды

```bash
# Войти в контейнер с kubectl
make kube-sh

# Выполнить kubectl команду
make kube-cmd CLUSTER=lab CMD="get pods -A"

# Войти в кластер
make kube-enter CLUSTER=lab

# Port-forward Kiali
make kiali-port-forward CLUSTER=lab

# Port-forward Istio Gateway
make istio-gw-port-forward CLUSTER=lab

# Port-forward Grafana
make grafana-port-forward CLUSTER=lab

# Port-forward Prometheus
make prom-port-forward CLUSTER=lab

# Остановить все port-forward
make kube-pf-stop
```

### Отчеты и мониторинг

```bash
# Сгенерировать HTML отчет
make lab-report

# Открыть Grafana
make grafana-open

# Получить URL Bookinfo
make bookinfo-url
```

## 🔧 Создание собственных пресетов

### Структура пресета

```yaml
---
# ПРЕСЕТ: Название (количество машин)
# 
# Описание: Подробное описание пресета
# 
# Использование: make lab-test SCENARIO=universal LAB_SPEC=molecule/presets/your-preset.yml
# 
# Автор: Ваше имя
# Сайт: https://your-site.com

docker_network: labnet

# Kind кластеры (опционально)
kind_clusters:
  - name: your-cluster
    workers: 2
    api_port: 6443
    addons:
      ingress_nginx: true
      metrics_server: true
      istio: true
      kiali: true
      prometheus_stack: true
    ingress_host_http_port: 8081
    ingress_host_https_port: 8443

# Образы для разных семейств ОС
images:
  debian: "ghcr.io/ansible-community/molecule-ubuntu-systemd:jammy"
  rhel: "quay.io/centos/centos:stream9-systemd"

# Настройки по умолчанию для systemd контейнеров
systemd_defaults:
    privileged: true
  command: "/sbin/init"
    volumes:
    - "/sys/fs/cgroup:/sys/fs/cgroup:ro"
  tmpfs:
    - "/run"
    - "/run/lock"
  capabilities:
    - "SYS_ADMIN"

# Определение хостов лаборатории
hosts:
  - name: host1
    family: debian
    group: webservers
    publish:
      - "8080:80"
  
  - name: host2
    type: dind
    group: dind
    publish:
      - "2375:2375"
  
  - name: host3
    type: dood
    family: rhel
    group: dood
    publish:
      - "8081:80"
    env:
      DOCKER_HOST: "unix:///var/run/docker.sock"
```

### Типы хостов

- **systemd** - обычные контейнеры с systemd (по умолчанию)
- **dind** - Docker-in-Docker контейнеры
- **dood** - Docker-outside-of-Docker контейнеры

### Семейства ОС

- **debian** - Debian/Ubuntu системы
- **rhel** - RHEL/CentOS системы

### Группы хостов

Можно создавать любые группы для организации хостов:

```yaml
hosts:
  - name: web1
    group: webservers
  - name: db1
    group: databases
  - name: cache1
    group: caches
```

### Публикация портов

```yaml
publish:
  - "8080:80"    # HTTP
  - "8443:443"   # HTTPS
  - "3306:3306"  # MySQL
  - "5432:5432"  # PostgreSQL
```

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

```yaml
env:
  DOCKER_HOST: "unix:///var/run/docker.sock"
  DATABASE_URL: "postgresql://user:pass@db:5432/mydb"
  DEBUG: "true"
```

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

```
ansible-template/
├── README.md                    # Основная документация
├── Makefile                     # Команды управления
├── docker-compose.yaml          # Docker Compose конфигурация
├── vault-password.txt           # Пароль для Ansible Vault
├── docs/                        # Документация
│   ├── universal-lab.md         # Руководство по лаборатории
│   ├── presets.md              # Описание пресетов
│   ├── roles.md                # Структура ролей
│   ├── examples.md             # Примеры использования
│   ├── troubleshooting.md     # Решение проблем
│   └── api.md                  # API Reference
├── ci-cd/                       # CI/CD конфигурация
│   ├── README.md               # Документация CI/CD
│   ├── .gitlab-ci.yml          # GitLab CI/CD
│   ├── gitlab/                 # GitLab Runner
│   └── dockerfiles/            # Dockerfile'ы для разных ОС
├── molecule/                   # Molecule конфигурация
│   ├── universal/              # Универсальный сценарий
│   │   ├── molecule.yml        # Конфигурация Molecule
│   │   ├── vars.yml            # Переменные по умолчанию
│   │   ├── create.yml          # Создание инфраструктуры
│   │   └── verify.yml          # Проверка работы
│   └── presets/                # Готовые пресеты
│       ├── minimal.yml         # Минимальная лаборатория
│       ├── webapp.yml          # Веб-приложение
│       ├── k8s-single.yml      # Kubernetes single
│       ├── dind-simple.yml     # DinD simple
│       ├── dood-simple.yml     # DOoD simple
│       └── ...                 # Другие пресеты
├── files/                      # Файлы для ролей
│   ├── playbooks/              # Ansible playbooks
│   ├── k8s/                    # Kubernetes манифесты
│   ├── grafana/                # Grafana дашборды
│   └── requirements.yml        # Ansible коллекции
├── roles/                      # Ansible роли
│   └── your_role/              # Ваши роли
├── scripts/                    # Скрипты (запускаются через Docker)
│   ├── report_html.py         # Генератор HTML отчетов
│   ├── snapshot.sh            # Создание снапшотов
│   ├── restore.sh             # Восстановление снапшотов
│   └── cleanup.sh             # Очистка лаборатории
├── vault/                      # Секреты и пароли
│   ├── .vault                  # Пароль для Ansible Vault
│   └── secrets.yml             # Зашифрованные секреты
└── .pre-commit-config.yaml    # Pre-commit конфигурация
```

## 🤝 Участие в разработке

### Установка для разработки

```bash
# Клонировать репозиторий
git clone https://github.com/your-username/ansible-template.git
cd ansible-template

# Установить pre-commit хуки
make pre-commit-install

# Запустить тесты
make lab-test
```

### Создание нового пресета

1. Создать файл в `molecule/presets/your-preset.yml`
2. Добавить описание в `docs/presets.md`
3. Протестировать: `make lab-test LAB_SPEC=molecule/presets/your-preset.yml`
4. Создать Pull Request

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

1. Создать структуру роли в `roles/your-role/`
2. Добавить описание в `docs/roles.md`
3. Протестировать с подходящим пресетом
4. Создать Pull Request

## 📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл [LICENSE](LICENSE) для подробностей.

## 👥 Авторы

- **Сергей Антропов** - *Основной разработчик* - [devops.org.ru](https://devops.org.ru)

## 🙏 Благодарности

- [Ansible](https://www.ansible.com/) - за отличный инструмент автоматизации
- [Molecule](https://molecule.readthedocs.io/) - за фреймворк тестирования
- [Docker](https://www.docker.com/) - за контейнеризацию
- [Kubernetes](https://kubernetes.io/) - за оркестрацию
- [Istio](https://istio.io/) - за service mesh

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

- **Документация**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/your-username/ansible-template/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-username/ansible-template/discussions)
- **Сайт**: [devops.org.ru](https://devops.org.ru)

---

**Сделано с ❤️ для сообщества DevOps**