DevOpsLab/README.md

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

📋 Описание

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

Установка

# Клонировать репозиторий
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

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

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

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

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

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

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

# Показать справку
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         # Очистить лабораторию

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

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

• Универсальная лаборатория - полное руководство по работе с лабораторией
• Пресеты - описание всех 21 готового пресета
• Роли - структура и создание Ansible ролей
• CI/CD - настройка CI/CD для Ansible ролей

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

• Примеры использования - практические примеры
• Troubleshooting - решение проблем
• API Reference - справочник по 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Kubernetes команды

# Войти в контейнер с 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

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

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

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

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

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

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

---
# ПРЕСЕТ: Название (количество машин)
# 
# Описание: Подробное описание пресета
# 
# Использование: 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 системы

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

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

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

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

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

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

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 конфигурация

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

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

# Клонировать репозиторий
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 для подробностей.

👥 Авторы

• Сергей Антропов - Основной разработчик - devops.org.ru

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

• Ansible - за отличный инструмент автоматизации
• Molecule - за фреймворк тестирования
• Docker - за контейнеризацию
• Kubernetes - за оркестрацию
• Istio - за service mesh

📞 Поддержка

• Документация: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Сайт: devops.org.ru

---

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