Sergey Antropoff
8071fba25f
- Создан новый README.md с полной документацией проекта - Перемещены все MD файлы в папку /docs - Создана структура документации: - docs/universal-lab.md - руководство по лаборатории - docs/presets.md - описание всех 21 пресета - docs/roles.md - структура и создание Ansible ролей - docs/examples.md - практические примеры использования - docs/troubleshooting.md - решение проблем - docs/api.md - справочник по API Основные возможности документации: - Полное описание всех возможностей лаборатории - 21 готовый пресет для различных сценариев - Подробные инструкции по использованию - Примеры создания собственных пресетов - Руководство по созданию Ansible ролей - Troubleshooting для решения проблем - API Reference для всех команд и параметров Структура проекта: - README.md - основная документация с ссылками - docs/ - централизованное хранение документации - molecule/presets/ - 21 готовый пресет - files/ - файлы для ролей и playbooks - scripts/ - скрипты для управления лабораторией Автор: Сергей Антропов Сайт: https://devops.org.ru
418 lines
16 KiB
Markdown
418 lines
16 KiB
Markdown
# Ansible Template - Универсальная лаборатория для тестирования Ansible ролей
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://www.ansible.com/)
|
||
[](https://molecule.readthedocs.io/)
|
||
[](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 lab-up
|
||
|
||
# Запустить минимальную лабораторию
|
||
make lab-test LAB_SPEC=molecule/presets/minimal.yml
|
||
|
||
# Посмотреть отчет
|
||
make lab-report
|
||
```
|
||
|
||
## 📚 Документация
|
||
|
||
### Основные разделы
|
||
|
||
- **[Универсальная лаборатория](docs/universal-lab.md)** - полное руководство по работе с лабораторией
|
||
- **[Пресеты](docs/presets.md)** - описание всех 21 готового пресета
|
||
- **[Роли](docs/roles.md)** - структура и создание 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
|
||
├── 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/ # Скрипты
|
||
│ ├── report_html.py # Генератор HTML отчетов
|
||
│ ├── snapshot.sh # Создание снапшотов
|
||
│ ├── restore.sh # Восстановление снапшотов
|
||
│ └── cleanup.sh # Очистка лаборатории
|
||
└── .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** |