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

- Создан новый 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
2025-10-22 13:29:47 +03:00
parent d32ca54f7b
commit 8071fba25f
8 changed files with 2511 additions and 52 deletions
--- a/docs/universal-lab.md
+++ b/docs/universal-lab.md
@@ -0,0 +1,295 @@
+# Универсальная лаборатория для тестирования Ansible ролей
+
+## Автор
+Сергей Антропов  
+Сайт: https://devops.org.ru
+
+## Описание
+
+Это универсальная лаборатория для тестирования Ansible ролей, созданная на основе предложений ChatGPT. Лаборатория поддерживает:
+
+- **Docker-in-Docker (DinD)** - полная изоляция контейнеров
+- **Docker-outside-of-Docker (DOoD)** - использование хостового Docker
+- **Kind кластеры** - локальные Kubernetes кластеры
+- **Helm charts** - nginx, prometheus-stack
+- **Istio service mesh** - с Kiali для мониторинга
+- **Prometheus + Grafana** - с автопровижинингом дашбордов
+- **HTML отчеты** - красивые отчеты о результатах тестирования
+
+## Структура проекта
+
+```
+molecule/
+├── universal/           # Универсальная лаборатория
+│   ├── molecule.yml     # Конфигурация Molecule
+│   ├── vars.yml         # Переменные лаборатории
+│   ├── create.yml       # Создание инфраструктуры
+│   ├── converge.yml     # Запуск ролей
+│   ├── verify.yml       # Проверка работы
+│   └── destroy.yml      # Очистка
+├── presets/             # Пресеты для разных сценариев
+│   └── k8s-kind.yml     # Пресет для Kubernetes
+└── default/             # Старый сценарий (для совместимости)
+
+files/
+├── requirements.yml     # Коллекции Ansible
+├── playbooks/
+│   └── site.yml         # Основной playbook
+└── k8s/                 # Kubernetes манифесты
+    └── istio/           # Istio конфигурации
+
+roles/                   # Ваши Ansible роли
+```
+
+## Использование
+
+### 1. Подготовка
+
+```bash
+# Создать файл с паролем для vault
+echo "test" > vault-password.txt
+
+# Создать каталог для ролей
+mkdir -p roles
+
+# Скопировать переменные окружения
+cp env.example .env
+# Отредактировать .env под ваши нужды
+```
+
+### 2. Запуск лаборатории
+
+```bash
+# Поднять контроллер
+make lab-up
+
+# Создать инфраструктуру
+make lab-create
+
+# Запустить роли
+make lab-converge
+
+# Проверить работу
+make lab-verify
+
+# Сгенерировать HTML отчет
+make lab-report
+
+# Уничтожить лабораторию
+make lab-destroy
+```
+
+### 3. Управление лабораторией
+
+```bash
+# Полный цикл тестирования
+make lab-test
+
+# Снапшоты и восстановление
+make lab-snapshot    # Сохранить состояние
+make lab-restore     # Восстановить из снапшота
+make lab-cleanup     # Очистить все
+
+# Сброс лаборатории
+make lab-reset
+```
+
+### 4. Пресеты для разных сценариев
+
+#### 🏗️ Классические пресеты (systemd контейнеры)
+```bash
+# Минимальная лаборатория (1-3 машины)
+make lab-test LAB_SPEC=molecule/presets/minimal.yml
+
+# Веб-приложение (3-5 машин)
+make lab-test LAB_SPEC=molecule/presets/webapp.yml
+
+# Микросервисы (5-8 машин)
+make lab-test LAB_SPEC=molecule/presets/microservices.yml
+
+# Высокая доступность (6-10 машин)
+make lab-test LAB_SPEC=molecule/presets/ha.yml
+
+# Kubernetes кластер (8-12 машин)
+make lab-test LAB_SPEC=molecule/presets/k8s-cluster.yml
+
+# CI/CD пайплайн (10-15 машин)
+make lab-test LAB_SPEC=molecule/presets/cicd.yml
+
+# Big Data кластер (12-18 машин)
+make lab-test LAB_SPEC=molecule/presets/bigdata.yml
+
+# Service Mesh (15-20 машин)
+make lab-test LAB_SPEC=molecule/presets/servicemesh.yml
+
+# Enterprise (18-20 машин)
+make lab-test LAB_SPEC=molecule/presets/enterprise.yml
+
+# Максимальный (20 машин)
+make lab-test LAB_SPEC=molecule/presets/maximum.yml
+```
+
+#### ☸️ Kubernetes пресеты
+```bash
+# Kubernetes Single Node (1 кластер)
+make lab-test LAB_SPEC=molecule/presets/k8s-single.yml
+
+# Kubernetes Multi-Cluster (3 кластера)
+make lab-test LAB_SPEC=molecule/presets/k8s-multi.yml
+
+# Kubernetes + Istio Full Stack (1 кластер с полным стеком)
+make lab-test LAB_SPEC=molecule/presets/k8s-istio-full.yml
+```
+
+#### 🐳 Docker-in-Docker (DinD) пресеты
+```bash
+# DinD Simple (3 DinD контейнера)
+make lab-test LAB_SPEC=molecule/presets/dind-simple.yml
+
+# DinD Swarm (5 DinD контейнеров)
+make lab-test LAB_SPEC=molecule/presets/dind-swarm.yml
+
+# DinD Compose (4 DinD контейнера)
+make lab-test LAB_SPEC=molecule/presets/dind-compose.yml
+```
+
+#### 🔗 Docker-outside-of-Docker (DOoD) пресеты
+```bash
+# DOoD Simple (3 DOoD контейнера)
+make lab-test LAB_SPEC=molecule/presets/dood-simple.yml
+
+# DOoD Mixed (5 DOoD + 2 systemd)
+make lab-test LAB_SPEC=molecule/presets/dood-mixed.yml
+```
+
+#### 🔀 Смешанные пресеты
+```bash
+# Mixed Kubernetes + DinD (1 K8s + 3 DinD)
+make lab-test LAB_SPEC=molecule/presets/mixed-k8s-dind.yml
+
+# Mixed Kubernetes + DOoD (1 K8s + 3 DOoD)
+make lab-test LAB_SPEC=molecule/presets/mixed-k8s-dood.yml
+
+# Mixed Full Stack (1 K8s + 2 DinD + 2 DOoD + 2 systemd)
+make lab-test LAB_SPEC=molecule/presets/mixed-full.yml
+```
+
+### 3. Работа с Kubernetes
+
+```bash
+# Войти в контейнер с kubectl
+make kube-sh
+
+# Выполнить команду kubectl
+make kube-cmd CLUSTER=lab CMD="get pods -A"
+
+# Войти в toolbox pod
+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
+```
+
+## Конфигурация
+
+### Переменные лаборатории (molecule/universal/vars.yml)
+
+```yaml
+# Сеть для лаборатории
+docker_network: labnet
+
+# Образы для разных семейств ОС
+images:
+  debian: "ghcr.io/ansible-community/molecule-ubuntu-systemd:jammy"
+  rhel: "quay.io/centos/centos:stream9-systemd"
+
+# Определение хостов
+hosts:
+  - name: etcd1
+    group: etcd
+    family: debian
+  - name: app-dind
+    group: apps
+    type: dind
+    publish:
+      - "8080:8080"
+
+# Kind кластеры
+kind_clusters:
+  - name: lab
+    workers: 2
+    addons:
+      ingress_nginx: true
+      istio: true
+      kiali: true
+```
+
+## Особенности
+
+### 1. Автогенерация инвентаря
+Инвентарь генерируется автоматически на основе определения хостов в `vars.yml`.
+
+### 2. Поддержка DinD и DOoD
+- **DinD**: Полная изоляция, каждый хост имеет свой Docker daemon
+- **DOoD**: Использование хостового Docker, меньше ресурсов
+
+### 3. Kubernetes интеграция
+- Автоматическое создание Kind кластеров
+- Установка Ingress NGINX, Metrics Server
+- Поддержка Istio и Kiali
+- Prometheus Stack с Grafana
+
+### 4. Мониторинг и отчеты
+- Автоматическая генерация HTML отчетов
+- Интеграция с Prometheus и Grafana
+- Дашборды для Istio
+
+## Troubleshooting
+
+### Проблемы с образами
+Если возникают проблемы с загрузкой образов, обновите `vars.yml`:
+
+```yaml
+images:
+  debian: "ubuntu:22.04"  # Используйте стандартные образы
+  rhel: "centos:8"
+```
+
+### Проблемы с Docker
+Убедитесь, что Docker socket доступен:
+
+```bash
+ls -la /var/run/docker.sock
+```
+
+### Проблемы с Molecule
+Если возникают проблемы с Molecule, попробуйте:
+
+```bash
+# Очистить кэш
+make lab-reset
+
+# Проверить конфигурацию
+docker exec ansible-controller bash -lc 'molecule lint -s universal'
+```
+
+## Дальнейшее развитие
+
+1. **Добавить поддержку Terraform** для создания инфраструктуры
+2. **Интегрировать с GitLab CI/CD** для автоматического тестирования
+3. **Добавить поддержку ARM64** для тестирования на Apple Silicon
+4. **Создать веб-интерфейс** для управления лабораторией
+5. **Добавить поддержку OpenShift** для enterprise сценариев
+
+## Лицензия
+
+MIT License
+
+## Контакты
+
+- Автор: Сергей Антропов
+- Сайт: https://devops.org.ru
+- Email: [ваш email]