Ansible/DevOpsLab
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

feat: Создана полная документация проекта с централизованным хранением

Browse Source 
- Создан новый 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
This commit is contained in:
Sergey Antropoff
2025-10-22 13:29:47 +03:00
parent d32ca54f7b
commit 8071fba25f
8 changed files with 2511 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

454
README.md
View File

@@ -1,62 +1,418 @@
# AnsibleTemplate
# Ansible Template - Универсальная лаборатория для тестирования Ansible ролей
Темплейт для создания, проверки и тестирование ролей Ansible с помощью контейнеров Docker.
[![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/)
### С чего начать?
## 📋 Описание
На вашей машине вам необходимо сбилдить образ, где будут запускаться все роли через docker-compose.
**Ansible Template** - это универсальная лаборатория для тестирования Ansible ролей в различных конфигурациях. Проект предоставляет гибкую и мощную среду для тестирования Ansible ролей, включая Docker-in-Docker (DinD), Docker-outside-of-Docker (DOoD), кластеры Kubernetes (Kind), Istio, Kiali, Prometheus и Grafana.
Это можно сделать самостоятельно:
### 🎯 Основные возможности
- **make docker build** - создание контейнера
- **make docker rebuild** - пересоздание контейнера, если были внесены изменения в Dockerfile
- **make docker prune** - очистить систему от лишних образов
- **make docker shell** - войти в контейнер Shell
- **make docker release** - собирает образ контейнера и пушит его в докер реджистри
- **make docker images** - собрать образы контейнеров с systemd, для удобного тестирования ролей
- **make images** - собрать и запушить все образы (основной Ansible, CentOS, Ubuntu) в Docker Hub (inecs/ansible)
- **Динамическое создание инфраструктуры** - автоматическое развертывание 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 отчеты** - красивые отчеты о результатах тестирования
- **Снапшоты** - сохранение и восстановление состояния лаборатории
Или ввести команду:
## 🚀 Быстрый старт
- **make init** - которая создаст файл секретов с паролем. Сбилдит образ. И создаст новую роль.
### Предварительные требования
### Работа с ролью
- **make role new** - создать новую роль из шаблона. Название роли пишется на английском, описание роли на любом языке
- **make role lint** - проверяет все роли в папке roles/* на наличие ошибок
- **make role test** - позволяет тестировать роль, указанную в molecule/default/converge.yml
сразу на двух контейнерах (RedHat и Ubuntu)
- **make role deploy** - запускает роль в продакшен. Все хосты берет из файла inventory/hosts
- Docker 20.0+
- Docker Compose 2.0+
- Make
- Git
### Работа с файлом переменных
### Установка
Все переменные защищены через **Ansible-Vault** и находятся в папке vars/secrets.yml
```bash
# Клонировать репозиторий
git clone https://github.com/your-username/ansible-template.git
cd ansible-template
Для смены пароля измените его в файле **./vault-password.txt**
# Создать необходимые файлы
echo "your-vault-password" > vault-password.txt
mkdir -p roles
mkdir -p files/playbooks
- **make vault create** - создать новый файл с учетом пароля в файле **./vault-password.txt**
- **make vault delete** - удалить файл с переменными
- **make vault edit** - отредактировать файл переменных
- **make vault show** - показать содержимое файла переменных
- **make vault rekey** - сменить пароль шифрования
- **make vault encrypt** - зашифровать файл секретов
- **make vault decrypt** - расшифровать файл секретов
### Работа с Git
- **make git push** - запушить изменения. С выбором ветки и вводом коммита.
- **make git pull** - получить изменения из репы
- **make git new** - создание нового брэнча имя cluster-branch_name для IaC подхода.
### Добавить свой образ контейнера для тестов
Что бы добавить или изменить докер-образы для тестирования ролей измените файл настроек молекулы
molecule/default/molecule.yml
```yaml
- name: ubuntu-instance
image: "your.docker-registry.com/your-image:latest"
privileged: true
pre_build_image: true
volumes:
- /sys/fs/cgroup:/sys/fs/cgroup:ro
# Установить pre-commit хуки (опционально)
make pre-commit-install
```
Помните, что образ обязательно должен содержать python не ниже версии 3.12 и systemd для нормального тестирования ролей.
### Первый запуск
```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**