diff --git a/README.md b/README.md index b371258..34a2774 100644 --- a/README.md +++ b/README.md @@ -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 для нормального тестирования ролей. \ No newline at end of file + +### Первый запуск + +```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** \ No newline at end of file diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..2e3e996 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,572 @@ +# API Reference + +## Автор +Сергей Антропов +Сайт: https://devops.org.ru + +## Описание + +Этот документ содержит справочник по API универсальной лаборатории, включая все доступные команды, параметры и конфигурации. + +## Содержание + +- [Makefile команды](#makefile-команды) +- [Пресеты API](#пресеты-api) +- [Kubernetes API](#kubernetes-api) +- [Docker API](#docker-api) +- [Molecule API](#molecule-api) +- [Отчеты API](#отчеты-api) +- [Скрипты API](#скрипты-api) + +## Makefile команды + +### Основные команды + +| Команда | Описание | Параметры | +|---------|----------|-----------| +| `make lab-up` | Поднять контроллер | - | +| `make lab-down` | Погасить контроллер | - | +| `make lab-sh` | Войти в контроллер | - | +| `make lab-test` | Полный цикл Molecule | `SCENARIO=universal` | +| `make lab-create` | Создать инфраструктуру | - | +| `make lab-converge` | Запустить роли | - | +| `make lab-verify` | Проверить работу | - | +| `make lab-destroy` | Уничтожить инфраструктуру | - | +| `make lab-reset` | Полный сброс | - | + +### Kubernetes команды + +| Команда | Описание | Параметры | +|---------|----------|-----------| +| `make kube-sh` | Shell с kubectl | - | +| `make kube-cmd` | Выполнить kubectl команду | `CLUSTER=lab CMD="get pods"` | +| `make kube-enter` | Войти в кластер | `CLUSTER=lab` | +| `make kiali-port-forward` | Port-forward Kiali | `CLUSTER=lab` | +| `make istio-gw-port-forward` | Port-forward Istio Gateway | `CLUSTER=lab` | +| `make grafana-port-forward` | Port-forward Grafana | `CLUSTER=lab` | +| `make prom-port-forward` | Port-forward Prometheus | `CLUSTER=lab` | +| `make kube-pf-stop` | Остановить все port-forward | - | + +### Отчеты и мониторинг + +| Команда | Описание | Параметры | +|---------|----------|-----------| +| `make lab-report` | Сгенерировать HTML отчет | - | +| `make lab-snapshot` | Сохранить снапшот | - | +| `make lab-restore` | Восстановить из снапшота | - | +| `make lab-cleanup` | Очистить лабораторию | - | +| `make bookinfo-url` | Получить URL Bookinfo | - | +| `make grafana-open` | Открыть Grafana | - | + +### Pre-commit команды + +| Команда | Описание | Параметры | +|---------|----------|-----------| +| `make pre-commit-install` | Установить pre-commit хуки | - | +| `make pre-commit-run` | Запустить pre-commit | - | + +## Пресеты API + +### Структура пресета + +```yaml +--- +# ПРЕСЕТ: Название (количество машин) +# +# Описание: Подробное описание пресета +# +# Использование: make lab-test SCENARIO=universal LAB_SPEC=molecule/presets/your-preset.yml +# +# Автор: Ваше имя +# Сайт: https://your-site.com + +# Сеть для лаборатории +docker_network: labnet + +# Kind кластеры (опционально) +kind_clusters: + - name: cluster-name + 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: host-name + family: debian|rhel + type: systemd|dind|dood + group: group-name + publish: + - "host-port:container-port" + env: + KEY: value + volumes: + - "host-path:container-path" + tmpfs: + - "/tmp" + capabilities: + - "SYS_ADMIN" +``` + +### Параметры хостов + +| Параметр | Тип | Описание | Обязательный | +|----------|-----|----------|--------------| +| `name` | string | Имя хоста | Да | +| `family` | string | Семейство ОС (debian/rhel) | Нет | +| `type` | string | Тип контейнера (systemd/dind/dood) | Нет | +| `group` | string | Группа хоста | Нет | +| `publish` | array | Публикация портов | Нет | +| `env` | object | Переменные окружения | Нет | +| `volumes` | array | Монтирование томов | Нет | +| `tmpfs` | array | Временные файловые системы | Нет | +| `capabilities` | array | Capabilities | Нет | + +### Параметры Kind кластеров + +| Параметр | Тип | Описание | Обязательный | +|----------|-----|----------|--------------| +| `name` | string | Имя кластера | Да | +| `workers` | integer | Количество worker узлов | Нет | +| `api_port` | integer | Порт API сервера | Нет | +| `addons` | object | Включенные аддоны | Нет | +| `ingress_host_http_port` | integer | HTTP порт для ingress | Нет | +| `ingress_host_https_port` | integer | HTTPS порт для ingress | Нет | + +### Аддоны Kind кластеров + +| Аддон | Тип | Описание | +|-------|-----|----------| +| `ingress_nginx` | boolean | Ingress NGINX контроллер | +| `metrics_server` | boolean | Metrics Server для метрик | +| `istio` | boolean | Istio service mesh | +| `kiali` | boolean | Kiali для визуализации | +| `prometheus_stack` | boolean | Prometheus + Grafana | + +## Kubernetes API + +### kubectl команды + +```bash +# Получить информацию о кластере +kubectl cluster-info + +# Получить ноды +kubectl get nodes + +# Получить поды +kubectl get pods -A + +# Получить сервисы +kubectl get svc -A + +# Получить события +kubectl get events --sort-by=.metadata.creationTimestamp + +# Описать ресурс +kubectl describe pod + +# Логи пода +kubectl logs + +# Войти в под +kubectl exec -it -- /bin/sh +``` + +### Port-forward команды + +```bash +# Port-forward сервиса +kubectl port-forward svc/ : + +# Port-forward пода +kubectl port-forward pod/ : + +# Port-forward в фоне +kubectl port-forward svc/ : & + +# Остановить все port-forward +pkill -f "kubectl .* port-forward" +``` + +### Istio команды + +```bash +# Проверить Istio +istioctl version + +# Установить Istio +istioctl install --set profile=demo + +# Удалить Istio +istioctl uninstall --purge + +# Проверить статус +istioctl proxy-status + +# Получить конфигурацию +istioctl proxy-config cluster +``` + +## Docker API + +### Docker команды + +```bash +# Список контейнеров +docker ps + +# Список образов +docker images + +# Список сетей +docker network ls + +# Список томов +docker volume ls + +# Информация о контейнере +docker inspect + +# Логи контейнера +docker logs + +# Войти в контейнер +docker exec -it /bin/sh +``` + +### Docker Compose команды + +```bash +# Запустить стек +docker-compose up -d + +# Остановить стек +docker-compose down + +# Логи стека +docker-compose logs + +# Масштабирование +docker-compose up --scale service=3 +``` + +### Docker Swarm команды + +```bash +# Инициализировать Swarm +docker swarm init + +# Присоединиться к Swarm +docker swarm join --token :2377 + +# Список нод +docker node ls + +# Создать сервис +docker service create --name + +# Масштабировать сервис +docker service scale =3 +``` + +## Molecule API + +### Molecule команды + +```bash +# Создать сценарий +molecule init scenario + +# Создать роль +molecule init role + +# Проверить синтаксис +molecule syntax + +# Проверить конфигурацию +molecule lint + +# Валидация +molecule validate + +# Создать инфраструктуру +molecule create + +# Запустить роли +molecule converge + +# Проверить работу +molecule verify + +# Уничтожить инфраструктуру +molecule destroy + +# Полный цикл +molecule test +``` + +### Конфигурация molecule.yml + +```yaml +--- +driver: + name: docker + +platforms: + - name: instance + image: "ghcr.io/ansible-community/molecule-ubuntu-systemd:jammy" + privileged: true + pre_build_image: true + command: "/sbin/init" + volumes: + - "/sys/fs/cgroup:/sys/fs/cgroup:ro" + capabilities: + - "SYS_ADMIN" + tmpfs: + - "/run" + - "/run/lock" + +provisioner: + name: ansible + config_options: + defaults: + stdout_callback: default + callbacks_enabled: profile_tasks + env: + ANSIBLE_STDOUT_CALLBACK: default + +dependency: + name: galaxy + enabled: false + +verifier: + name: ansible + +lint: |- + set -e + ansible-lint +``` + +## Отчеты API + +### HTML отчет + +```bash +# Генерация отчета +python3 scripts/report_html.py + +# Параметры +# input.json - JSON файл с данными +# output.html - HTML файл для вывода +``` + +### JSON структура + +```json +{ + "timestamp": "2024-01-01T00:00:00Z", + "idempotence_raw": "changed=0", + "haproxy_select1": "1", + "helm_ingress_toolbox_raw": "ingress ready", + "istio_kiali_raw": "istio-system pods running", + "istio_bookinfo_raw": "bookinfo deployed", + "k8s_overview_raw": "nodes ready" +} +``` + +### HTML структура + +```html + + + + + Lab Report + + + + +
+
+

Ansible Lab Report

+
generated: timestamp
+
+
+ +
+
+ + +``` + +## Скрипты API + +### snapshot.sh + +```bash +#!/usr/bin/env bash +# Создание снапшотов лаборатории + +# Параметры +OUT_DIR="snapshots" + +# Создать директорию +mkdir -p "$OUT_DIR" + +# Получить ID контейнеров +ids=$(docker ps -q --filter "label=ansible.lab=true") + +# Создать снапшоты +for id in $ids; do + name=$(docker inspect --format '{{.Name}}' "$id" | sed 's#^/##') + img="lab-snap-$name:latest" + echo "[snapshot] $name -> $img" + docker commit "$id" "$img" >/dev/null + echo "$img" > "$OUT_DIR/$name.image" +done +``` + +### restore.sh + +```bash +#!/usr/bin/env bash +# Восстановление из снапшотов + +# Параметры +IN_DIR="snapshots" + +# Проверить директорию +[ -d "$IN_DIR" ] || { echo "No snapshots dir"; exit 1; } + +# Восстановить контейнеры +for f in "$IN_DIR"/*.image; do + [ -f "$f" ] || continue + name=$(basename "$f" .image) + img=$(cat "$f") + echo "[restore] $name from $img" + docker rm -f "$name" >/dev/null 2>&1 || true + docker run -d --name "$name" "$img" >/dev/null +done +``` + +### cleanup.sh + +```bash +#!/usr/bin/env bash +# Очистка лаборатории + +echo "[cleanup] removing lab containers/volumes/networks" + +# Удалить контейнеры +docker ps -aq --filter "label=ansible.lab=true" | xargs -r docker rm -f + +# Удалить тома +docker volume ls -q --filter "name=_docker$" | xargs -r docker volume rm + +# Удалить сеть +docker network rm labnet >/dev/null 2>&1 || true + +echo "done." +``` + +## Переменные окружения + +### Основные переменные + +| Переменная | Описание | Значение по умолчанию | +|------------|----------|----------------------| +| `LAB_SPEC` | Путь к пресету | `molecule/presets/minimal.yml` | +| `SCENARIO` | Сценарий Molecule | `universal` | +| `COMPOSE` | Docker Compose команда | `docker compose` | +| `ROLES_DIR` | Директория с ролями | `./roles` | +| `LAB_PAUSE_MINUTES` | Пауза для ручной проверки | `10` | + +### Kubernetes переменные + +| Переменная | Описание | Значение по умолчанию | +|------------|----------|----------------------| +| `KUBECONFIG` | Путь к kubeconfig | `~/.kube/config` | +| `KUBE_CONTEXT` | Контекст Kubernetes | `kind-lab` | +| `ISTIO_VERSION` | Версия Istio | `1.22.1` | +| `KIND_VERSION` | Версия Kind | `v0.23.0` | + +### Docker переменные + +| Переменная | Описание | Значение по умолчанию | +|------------|----------|----------------------| +| `DOCKER_HOST` | Docker daemon адрес | `unix:///var/run/docker.sock` | +| `DOCKER_TLS_CERTDIR` | Директория TLS сертификатов | `""` | +| `DOCKER_BUILDKIT` | Использовать BuildKit | `1` | + +## Конфигурационные файлы + +### docker-compose.yaml + +```yaml +version: "3.9" + +services: + ansible-controller: + image: quay.io/ansible/creator-ee:latest + container_name: ansible-controller + privileged: true + command: sleep infinity + environment: + DOCKER_HOST: unix:///var/run/docker.sock + ANSIBLE_VAULT_PASSWORD_FILE: /ansible/vault-password.txt + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ./molecule:/ansible/molecule + - ./files:/ansible/files + - ./vault-password.txt:/ansible/vault-password.txt + - ${ROLES_DIR:-./roles}:/ansible/roles:ro + working_dir: /ansible +``` + +### .pre-commit-config.yaml + +```yaml +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + - repo: https://github.com/ansible/ansible-lint + rev: v6.17.2 + hooks: + - id: ansible-lint +``` + +## Заключение + +Этот справочник содержит все необходимые API для работы с универсальной лабораторией. Для получения дополнительной информации обратитесь к [основной документации](universal-lab.md) и [примерам использования](examples.md). diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..c058c00 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,462 @@ +# Примеры использования + +## Автор +Сергей Антропов +Сайт: https://devops.org.ru + +## Описание + +Этот документ содержит практические примеры использования универсальной лаборатории для различных сценариев тестирования Ansible ролей. + +## Содержание + +- [Базовые примеры](#базовые-примеры) +- [Kubernetes примеры](#kubernetes-примеры) +- [Docker примеры](#docker-примеры) +- [Смешанные примеры](#смешанные-примеры) +- [Мониторинг и отчеты](#мониторинг-и-отчеты) +- [Troubleshooting](#troubleshooting) + +## Базовые примеры + +### Пример 1: Тестирование веб-сервера + +```bash +# Запустить веб-приложение пресет +make lab-test LAB_SPEC=molecule/presets/webapp.yml + +# Проверить статус +make lab-verify + +# Посмотреть отчет +make lab-report +``` + +### Пример 2: Тестирование базы данных + +```bash +# Запустить пресет с базой данных +make lab-test LAB_SPEC=molecule/presets/ha.yml + +# Проверить подключение к БД +make kube-cmd CLUSTER=lab CMD="exec -it postgres-0 -- psql -U postgres -c 'SELECT 1;'" +``` + +### Пример 3: Тестирование микросервисов + +```bash +# Запустить микросервисный пресет +make lab-test LAB_SPEC=molecule/presets/microservices.yml + +# Проверить API Gateway +curl http://localhost:8000/health +``` + +## Kubernetes примеры + +### Пример 1: Простой Kubernetes кластер + +```bash +# Запустить одиночный Kind кластер +make lab-test LAB_SPEC=molecule/presets/k8s-single.yml + +# Войти в кластер +make kube-sh + +# Проверить ноды +kubectl get nodes + +# Проверить поды +kubectl get pods -A +``` + +### Пример 2: Мульти-кластерная конфигурация + +```bash +# Запустить мульти-кластер +make lab-test LAB_SPEC=molecule/presets/k8s-multi.yml + +# Переключиться между кластерами +kubectl config use-context kind-dev +kubectl get nodes + +kubectl config use-context kind-staging +kubectl get nodes + +kubectl config use-context kind-prod +kubectl get nodes +``` + +### Пример 3: Istio Service Mesh + +```bash +# Запустить полный Istio стек +make lab-test LAB_SPEC=molecule/presets/k8s-istio-full.yml + +# Port-forward Kiali +make kiali-port-forward CLUSTER=istio-full + +# Port-forward Istio Gateway +make istio-gw-port-forward CLUSTER=istio-full + +# Открыть Kiali +open http://localhost:20001 + +# Открыть Bookinfo +open http://localhost:8082/productpage +``` + +### Пример 4: Мониторинг Kubernetes + +```bash +# Port-forward Grafana +make grafana-port-forward CLUSTER=istio-full + +# Port-forward Prometheus +make prom-port-forward CLUSTER=istio-full + +# Открыть Grafana +open http://localhost:3000 + +# Открыть Prometheus +open http://localhost:9090 +``` + +## Docker примеры + +### Пример 1: Docker-in-Docker + +```bash +# Запустить DinD пресет +make lab-test LAB_SPEC=molecule/presets/dind-simple.yml + +# Войти в DinD контейнер +docker exec -it dind1 sh + +# Внутри контейнера проверить Docker +docker ps +docker images +``` + +### Пример 2: Docker Swarm + +```bash +# Запустить Docker Swarm пресет +make lab-test LAB_SPEC=molecule/presets/dind-swarm.yml + +# Войти в manager +docker exec -it swarm-manager sh + +# Инициализировать Swarm +docker swarm init + +# Присоединить workers +docker node ls +``` + +### Пример 3: Docker Compose + +```bash +# Запустить Compose пресет +make lab-test LAB_SPEC=molecule/presets/dind-compose.yml + +# Войти в compose контейнер +docker exec -it compose-web sh + +# Создать docker-compose.yml +cat > docker-compose.yml << EOF +version: '3.8' +services: + web: + image: nginx:alpine + ports: + - "80:80" + api: + image: node:alpine + ports: + - "3000:3000" +EOF + +# Запустить стек +docker-compose up -d +``` + +### Пример 4: Docker-outside-of-Docker + +```bash +# Запустить DOoD пресет +make lab-test LAB_SPEC=molecule/presets/dood-simple.yml + +# Войти в DOoD контейнер +docker exec -it dood1 sh + +# Проверить доступ к Docker daemon хоста +docker ps +docker images +``` + +## Смешанные примеры + +### Пример 1: Kubernetes + DinD + +```bash +# Запустить смешанный пресет +make lab-test LAB_SPEC=molecule/presets/mixed-k8s-dind.yml + +# Проверить Kubernetes +make kube-cmd CLUSTER=hybrid CMD="get nodes" + +# Проверить DinD +docker exec -it dind-dev sh +docker ps +``` + +### Пример 2: Kubernetes + DOoD + +```bash +# Запустить смешанный пресет +make lab-test LAB_SPEC=molecule/presets/mixed-k8s-dood.yml + +# Проверить Kubernetes +make kube-cmd CLUSTER=hybrid CMD="get pods -A" + +# Проверить DOoD +docker exec -it dood-web sh +docker ps +``` + +### Пример 3: Полная гибридная конфигурация + +```bash +# Запустить полный смешанный пресет +make lab-test LAB_SPEC=molecule/presets/mixed-full.yml + +# Проверить все компоненты +make kube-cmd CLUSTER=full-stack CMD="get nodes" +docker exec -it dind-dev sh +docker exec -it dood-web sh +``` + +## Мониторинг и отчеты + +### Пример 1: Генерация HTML отчета + +```bash +# Запустить тест +make lab-test LAB_SPEC=molecule/presets/enterprise.yml + +# Сгенерировать отчет +make lab-report + +# Открыть отчет +open reports/lab-report.html +``` + +### Пример 2: Снапшоты + +```bash +# Создать снапшот +make lab-snapshot + +# Восстановить из снапшота +make lab-restore + +# Очистить лабораторию +make lab-cleanup +``` + +### Пример 3: Мониторинг в реальном времени + +```bash +# Port-forward всех сервисов мониторинга +make grafana-port-forward CLUSTER=lab +make prom-port-forward CLUSTER=lab +make kiali-port-forward CLUSTER=lab + +# Открыть все дашборды +open http://localhost:3000 # Grafana +open http://localhost:9090 # Prometheus +open http://localhost:20001 # Kiali +``` + +## Troubleshooting + +### Пример 1: Проблемы с портами + +```bash +# Проверить занятые порты +netstat -tulpn | grep :8080 + +# Остановить все port-forward +make kube-pf-stop + +# Перезапустить лабораторию +make lab-reset +``` + +### Пример 2: Проблемы с Docker + +```bash +# Проверить Docker daemon +docker ps + +# Перезапустить Docker +sudo systemctl restart docker + +# Очистить Docker +docker system prune -a +``` + +### Пример 3: Проблемы с Kubernetes + +```bash +# Проверить Kind кластеры +kind get clusters + +# Удалить проблемный кластер +kind delete cluster --name lab + +# Пересоздать кластер +make lab-create +``` + +### Пример 4: Проблемы с ресурсами + +```bash +# Проверить использование ресурсов +docker stats + +# Ограничить ресурсы +docker run --memory=512m --cpus=1.0 your-image + +# Очистить неиспользуемые ресурсы +make lab-cleanup +``` + +## Продвинутые примеры + +### Пример 1: Создание собственного пресета + +```bash +# Создать новый пресет +cat > molecule/presets/my-custom.yml << EOF +--- +# ПРЕСЕТ: Мой кастомный пресет +# +# Описание: Кастомная конфигурация для моих нужд +# +# Использование: make lab-test LAB_SPEC=molecule/presets/my-custom.yml + +docker_network: labnet + +images: + debian: "ghcr.io/ansible-community/molecule-ubuntu-systemd:jammy" + rhel: "quay.io/centos/centos:stream9-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: my-web + family: debian + group: webservers + publish: + - "8080:80" + + - name: my-db + family: rhel + group: databases + publish: + - "5432:5432" +EOF + +# Протестировать пресет +make lab-test LAB_SPEC=molecule/presets/my-custom.yml +``` + +### Пример 2: Создание собственной роли + +```bash +# Создать структуру роли +mkdir -p roles/my-role/{tasks,handlers,templates,files,vars,defaults,meta} + +# Создать основной task +cat > roles/my-role/tasks/main.yml << EOF +--- +- name: Install nginx + package: + name: nginx + state: present + +- name: Start nginx + service: + name: nginx + state: started + enabled: true +EOF + +# Создать playbook +cat > files/playbooks/my-playbook.yml << EOF +--- +- name: Deploy my role + hosts: webservers + become: true + roles: + - my-role +EOF + +# Протестировать роль +make lab-test LAB_SPEC=molecule/presets/webapp.yml +``` + +### Пример 3: Интеграция с CI/CD + +```bash +# Создать GitHub Actions workflow +cat > .github/workflows/test.yml << EOF +name: Test Ansible Roles + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Setup Docker + run: | + docker-compose up -d + + - name: Run tests + run: | + make lab-test LAB_SPEC=molecule/presets/minimal.yml + + - name: Generate report + run: | + make lab-report + + - name: Upload report + uses: actions/upload-artifact@v3 + with: + name: lab-report + path: reports/lab-report.html +EOF +``` + +## Заключение + +Эти примеры демонстрируют основные возможности универсальной лаборатории. Для получения дополнительной информации обратитесь к [основной документации](universal-lab.md) и [описанию пресетов](presets.md). diff --git a/molecule/presets/README.md b/docs/presets.md similarity index 100% rename from molecule/presets/README.md rename to docs/presets.md diff --git a/docs/roles.md b/docs/roles.md new file mode 100644 index 0000000..274debc --- /dev/null +++ b/docs/roles.md @@ -0,0 +1,420 @@ +# Ansible Роли + +## Автор +Сергей Антропов +Сайт: https://devops.org.ru + +## Описание + +Этот документ описывает структуру, создание и использование Ansible ролей в универсальной лаборатории. + +## Содержание + +- [Структура роли](#структура-роли) +- [Создание роли](#создание-роли) +- [Использование роли](#использование-роли) +- [Тестирование роли](#тестирование-роли) +- [Лучшие практики](#лучшие-практики) +- [Примеры ролей](#примеры-ролей) + +## Структура роли + +``` +roles/ +└── your_role/ + ├── tasks/ # Основные задачи + │ └── main.yml + ├── handlers/ # Обработчики событий + │ └── main.yml + ├── templates/ # Jinja2 шаблоны + │ └── config.j2 + ├── files/ # Статические файлы + │ └── config.conf + ├── vars/ # Переменные роли + │ └── main.yml + ├── defaults/ # Переменные по умолчанию + │ └── main.yml + ├── meta/ # Метаданные роли + │ └── main.yml + └── tests/ # Тесты роли + ├── inventory + └── test.yml +``` + +### Описание директорий + +| Директория | Описание | Обязательная | +|------------|----------|--------------| +| `tasks/` | Основные задачи роли | Да | +| `handlers/` | Обработчики событий | Нет | +| `templates/` | Jinja2 шаблоны | Нет | +| `files/` | Статические файлы | Нет | +| `vars/` | Переменные роли | Нет | +| `defaults/` | Переменные по умолчанию | Нет | +| `meta/` | Метаданные роли | Нет | +| `tests/` | Тесты роли | Нет | + +## Создание роли + +### Автоматическое создание + +```bash +# Создать роль с помощью ansible-galaxy +ansible-galaxy init your_role + +# Создать роль в определенной директории +ansible-galaxy init your_role --init-path roles/ +``` + +### Ручное создание + +```bash +# Создать структуру роли +mkdir -p roles/your_role/{tasks,handlers,templates,files,vars,defaults,meta,tests} + +# Создать основной task +cat > roles/your_role/tasks/main.yml << EOF +--- +- name: Install package + package: + name: "{{ package_name }}" + state: present + +- name: Start service + service: + name: "{{ service_name }}" + state: started + enabled: true +EOF + +# Создать переменные по умолчанию +cat > roles/your_role/defaults/main.yml << EOF +--- +package_name: nginx +service_name: nginx +EOF +``` + +## Использование роли + +### В playbook + +```yaml +--- +- name: Deploy web server + hosts: webservers + become: true + roles: + - your_role +``` + +### С переменными + +```yaml +--- +- name: Deploy web server + hosts: webservers + become: true + roles: + - role: your_role + vars: + package_name: apache2 + service_name: apache2 +``` + +### С условиями + +```yaml +--- +- name: Deploy web server + hosts: webservers + become: true + roles: + - role: your_role + when: ansible_os_family == "Debian" +``` + +## Тестирование роли + +### Создание тестов + +```bash +# Создать тестовый playbook +cat > roles/your_role/tests/test.yml << EOF +--- +- name: Test role + hosts: all + become: true + roles: + - your_role +EOF + +# Создать инвентарь для тестов +cat > roles/your_role/tests/inventory << EOF +[webservers] +localhost ansible_connection=local +EOF +``` + +### Запуск тестов + +```bash +# Запустить тест роли +ansible-playbook -i roles/your_role/tests/inventory roles/your_role/tests/test.yml + +# Запустить тест с Molecule +molecule test +``` + +## Лучшие практики + +### Структура задач + +```yaml +--- +# tasks/main.yml +- name: Install package + package: + name: "{{ package_name }}" + state: present + notify: restart service + +- name: Configure service + template: + src: config.j2 + dest: /etc/service/config.conf + notify: restart service + +- name: Start service + service: + name: "{{ service_name }}" + state: started + enabled: true +``` + +### Обработчики + +```yaml +--- +# handlers/main.yml +- name: restart service + service: + name: "{{ service_name }}" + state: restarted +``` + +### Переменные + +```yaml +--- +# defaults/main.yml +package_name: nginx +service_name: nginx +config_file: /etc/nginx/nginx.conf +port: 80 + +# vars/main.yml +service_user: nginx +service_group: nginx +``` + +### Метаданные + +```yaml +--- +# meta/main.yml +galaxy_info: + author: Your Name + description: Your role description + company: Your Company + license: MIT + min_ansible_version: "2.9" + platforms: + - name: Ubuntu + versions: + - focal + - jammy + - name: CentOS + versions: + - 8 + - 9 + galaxy_tags: + - web + - nginx +dependencies: [] +``` + +## Примеры ролей + +### Роль для веб-сервера + +```yaml +--- +# tasks/main.yml +- name: Install nginx + package: + name: nginx + state: present + +- name: Configure nginx + template: + src: nginx.conf.j2 + dest: /etc/nginx/nginx.conf + notify: restart nginx + +- name: Start nginx + service: + name: nginx + state: started + enabled: true +``` + +```yaml +--- +# defaults/main.yml +nginx_port: 80 +nginx_ssl_port: 443 +nginx_user: www-data +nginx_worker_processes: auto +``` + +### Роль для базы данных + +```yaml +--- +# tasks/main.yml +- name: Install PostgreSQL + package: + name: postgresql + state: present + +- name: Start PostgreSQL + service: + name: postgresql + state: started + enabled: true + +- name: Create database + postgresql_db: + name: "{{ db_name }}" + state: present + +- name: Create user + postgresql_user: + name: "{{ db_user }}" + password: "{{ db_password }}" + state: present +``` + +### Роль для мониторинга + +```yaml +--- +# tasks/main.yml +- name: Install Prometheus + package: + name: prometheus + state: present + +- name: Configure Prometheus + template: + src: prometheus.yml.j2 + dest: /etc/prometheus/prometheus.yml + notify: restart prometheus + +- name: Start Prometheus + service: + name: prometheus + state: started + enabled: true +``` + +## Интеграция с лабораторией + +### Использование в пресетах + +```yaml +--- +# molecule/presets/webapp.yml +hosts: + - name: web1 + group: webservers + family: debian + publish: + - "8080:80" + + - name: db1 + group: databases + family: rhel + publish: + - "5432:5432" +``` + +### Playbook для ролей + +```yaml +--- +# files/playbooks/site.yml +- name: Deploy web servers + hosts: webservers + become: true + roles: + - nginx + - ssl + +- name: Deploy databases + hosts: databases + become: true + roles: + - postgresql + - backup + +- name: Deploy monitoring + hosts: monitoring + become: true + roles: + - prometheus + - grafana +``` + +### Тестирование с различными пресетами + +```bash +# Тестирование с минимальным пресетом +make lab-test LAB_SPEC=molecule/presets/minimal.yml + +# Тестирование с веб-приложением +make lab-test LAB_SPEC=molecule/presets/webapp.yml + +# Тестирование с микросервисами +make lab-test LAB_SPEC=molecule/presets/microservices.yml +``` + +## Публикация роли + +### В Ansible Galaxy + +```bash +# Установить ansible-galaxy +pip install ansible-galaxy + +# Публиковать роль +ansible-galaxy import your-username your-role + +# Или через GitHub +ansible-galaxy import your-username your-role --github-user your-username +``` + +### В приватном репозитории + +```bash +# Установить роль из Git +ansible-galaxy install git+https://github.com/your-username/your-role.git + +# Установить роль из файла +ansible-galaxy install your-role.tar.gz +``` + +## Заключение + +Этот документ описывает основные принципы создания и использования Ansible ролей в универсальной лаборатории. Для получения дополнительной информации обратитесь к [основной документации](universal-lab.md) и [примерам использования](examples.md). \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..4a60b2d --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,652 @@ +# Troubleshooting + +## Автор +Сергей Антропов +Сайт: https://devops.org.ru + +## Описание + +Этот документ содержит решения наиболее распространенных проблем при работе с универсальной лабораторией. + +## Содержание + +- [Общие проблемы](#общие-проблемы) +- [Проблемы с Docker](#проблемы-с-docker) +- [Проблемы с Kubernetes](#проблемы-с-kubernetes) +- [Проблемы с портами](#проблемы-с-портами) +- [Проблемы с ресурсами](#проблемы-с-ресурсами) +- [Проблемы с сетью](#проблемы-с-сетью) +- [Проблемы с Ansible](#проблемы-с-ansible) +- [Проблемы с Molecule](#проблемы-с-molecule) +- [Проблемы с пресетами](#проблемы-с-пресетами) +- [Проблемы с отчетами](#проблемы-с-отчетами) + +## Общие проблемы + +### Проблема: Лаборатория не запускается + +**Симптомы:** +- Команда `make lab-up` завершается с ошибкой +- Контейнеры не создаются +- Ошибки в логах Docker + +**Решение:** +```bash +# Проверить статус Docker +docker ps +docker version + +# Перезапустить Docker +sudo systemctl restart docker + +# Очистить Docker +docker system prune -a + +# Перезапустить лабораторию +make lab-reset +``` + +### Проблема: Команды Make не работают + +**Симптомы:** +- `make: command not found` +- Ошибки в Makefile + +**Решение:** +```bash +# Установить Make +# Ubuntu/Debian +sudo apt-get install make + +# CentOS/RHEL +sudo yum install make + +# macOS +brew install make + +# Проверить версию +make --version +``` + +### Проблема: Недостаточно прав + +**Симптомы:** +- `Permission denied` +- Ошибки доступа к файлам + +**Решение:** +```bash +# Проверить права на файлы +ls -la + +# Установить права +chmod +x scripts/*.sh +chmod 644 *.yml + +# Добавить пользователя в группу docker +sudo usermod -aG docker $USER +newgrp docker +``` + +## Проблемы с Docker + +### Проблема: Docker daemon не запущен + +**Симптомы:** +- `Cannot connect to the Docker daemon` +- `docker: command not found` + +**Решение:** +```bash +# Запустить Docker daemon +sudo systemctl start docker +sudo systemctl enable docker + +# Проверить статус +sudo systemctl status docker + +# Проверить доступ +docker ps +``` + +### Проблема: Недостаточно места на диске + +**Симптомы:** +- `No space left on device` +- Ошибки создания контейнеров + +**Решение:** +```bash +# Проверить использование диска +df -h + +# Очистить Docker +docker system prune -a +docker volume prune +docker network prune + +# Удалить неиспользуемые образы +docker image prune -a +``` + +### Проблема: Конфликты портов + +**Симптомы:** +- `Port is already in use` +- Ошибки привязки портов + +**Решение:** +```bash +# Найти процесс, использующий порт +sudo netstat -tulpn | grep :8080 +sudo lsof -i :8080 + +# Убить процесс +sudo kill -9 + +# Или изменить порт в пресете +publish: + - "8081:80" # Вместо 8080:80 +``` + +### Проблема: DinD контейнеры не работают + +**Симптомы:** +- DinD контейнеры не запускаются +- Ошибки Docker-in-Docker + +**Решение:** +```bash +# Проверить privileged режим +docker run --privileged -d docker:dind + +# Проверить доступ к Docker socket +docker run -v /var/run/docker.sock:/var/run/docker.sock docker:latest ps + +# Перезапустить с правильными параметрами +make lab-reset +make lab-create +``` + +## Проблемы с Kubernetes + +### Проблема: Kind кластер не создается + +**Симптомы:** +- `kind create cluster` завершается с ошибкой +- Кластер не доступен + +**Решение:** +```bash +# Проверить Kind +kind version + +# Удалить существующие кластеры +kind delete cluster --name lab + +# Очистить Docker +docker system prune -a + +# Пересоздать кластер +make lab-create +``` + +### Проблема: kubectl не работает + +**Симптомы:** +- `kubectl: command not found` +- Ошибки подключения к кластеру + +**Решение:** +```bash +# Установить kubectl +curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" +chmod +x kubectl +sudo mv kubectl /usr/local/bin/ + +# Проверить конфигурацию +kubectl config get-contexts + +# Переключиться на правильный контекст +kubectl config use-context kind-lab +``` + +### Проблема: Pods не запускаются + +**Симптомы:** +- Pods в состоянии Pending +- Ошибки в логах pods + +**Решение:** +```bash +# Проверить статус pods +kubectl get pods -A +kubectl describe pod + +# Проверить события +kubectl get events --sort-by=.metadata.creationTimestamp + +# Проверить ресурсы +kubectl top nodes +kubectl top pods +``` + +### Проблема: Istio не устанавливается + +**Симптомы:** +- Istio компоненты не запускаются +- Ошибки в Istio логах + +**Решение:** +```bash +# Проверить Istio +istioctl version + +# Переустановить Istio +istioctl uninstall --purge +istioctl install --set profile=demo + +# Проверить статус +kubectl get pods -n istio-system +``` + +## Проблемы с портами + +### Проблема: Порт уже используется + +**Симптомы:** +- `bind: address already in use` +- Ошибки привязки портов + +**Решение:** +```bash +# Найти процесс +sudo lsof -i :8080 + +# Убить процесс +sudo kill -9 + +# Или изменить порт в пресете +publish: + - "8081:80" +``` + +### Проблема: Port-forward не работает + +**Симптомы:** +- Port-forward не устанавливается +- Ошибки подключения + +**Решение:** +```bash +# Остановить все port-forward +make kube-pf-stop + +# Проверить доступность сервиса +kubectl get svc -n istio-system + +# Перезапустить port-forward +make kiali-port-forward CLUSTER=lab +``` + +## Проблемы с ресурсами + +### Проблема: Недостаточно памяти + +**Симптомы:** +- `Out of memory` +- Контейнеры завершаются + +**Решение:** +```bash +# Проверить память +free -h +docker stats + +# Ограничить ресурсы +docker run --memory=512m your-image + +# Или уменьшить количество контейнеров в пресете +``` + +### Проблема: Недостаточно CPU + +**Симптомы:** +- Медленная работа +- Высокая нагрузка на CPU + +**Решение:** +```bash +# Проверить CPU +top +htop + +# Ограничить CPU +docker run --cpus=1.0 your-image + +# Или использовать более легкие образы +``` + +### Проблема: Недостаточно места на диске + +**Симптомы:** +- `No space left on device` +- Ошибки записи + +**Решение:** +```bash +# Проверить место +df -h + +# Очистить Docker +docker system prune -a +docker volume prune + +# Удалить неиспользуемые образы +docker image prune -a +``` + +## Проблемы с сетью + +### Проблема: Контейнеры не могут связаться + +**Симптомы:** +- Ping не работает между контейнерами +- Ошибки сети + +**Решение:** +```bash +# Проверить сеть +docker network ls +docker network inspect labnet + +# Пересоздать сеть +docker network rm labnet +docker network create labnet + +# Перезапустить лабораторию +make lab-reset +``` + +### Проблема: DNS не работает + +**Симптомы:** +- Не удается разрешить имена +- Ошибки DNS + +**Решение:** +```bash +# Проверить DNS +nslookup google.com + +# Перезапустить Docker +sudo systemctl restart docker + +# Проверить resolv.conf +cat /etc/resolv.conf +``` + +## Проблемы с Ansible + +### Проблема: Ansible не найден + +**Симптомы:** +- `ansible: command not found` +- Ошибки выполнения playbook + +**Решение:** +```bash +# Установить Ansible +pip install ansible + +# Или через пакетный менеджер +sudo apt-get install ansible + +# Проверить версию +ansible --version +``` + +### Проблема: Ошибки в playbook + +**Симптомы:** +- Синтаксические ошибки +- Ошибки выполнения задач + +**Решение:** +```bash +# Проверить синтаксис +ansible-playbook --syntax-check playbook.yml + +# Запустить в режиме отладки +ansible-playbook -vvv playbook.yml + +# Проверить инвентарь +ansible-inventory --list +``` + +### Проблема: Ошибки подключения + +**Симптомы:** +- `Connection refused` +- Ошибки SSH + +**Решение:** +```bash +# Проверить подключение +ansible all -m ping + +# Проверить SSH ключи +ssh-keygen -t rsa -b 4096 +ssh-copy-id user@host + +# Или использовать пароль +ansible all -m ping -k +``` + +## Проблемы с Molecule + +### Проблема: Molecule не найден + +**Симптомы:** +- `molecule: command not found` +- Ошибки выполнения molecule + +**Решение:** +```bash +# Установить Molecule +pip install molecule + +# Или через пакетный менеджер +sudo apt-get install molecule + +# Проверить версию +molecule --version +``` + +### Проблема: Ошибки в molecule.yml + +**Симптомы:** +- Синтаксические ошибки в конфигурации +- Ошибки валидации + +**Решение:** +```bash +# Проверить синтаксис +molecule syntax + +# Проверить конфигурацию +molecule lint + +# Исправить ошибки +molecule validate +``` + +### Проблема: Ошибки драйвера + +**Симптомы:** +- Ошибки Docker драйвера +- Проблемы с контейнерами + +**Решение:** +```bash +# Проверить драйвер +molecule driver list + +# Установить Docker драйвер +pip install molecule-docker + +# Перезапустить Molecule +molecule destroy +molecule create +``` + +## Проблемы с пресетами + +### Проблема: Пресет не найден + +**Симптомы:** +- `File not found` +- Ошибки загрузки пресета + +**Решение:** +```bash +# Проверить путь +ls -la molecule/presets/ + +# Проверить синтаксис YAML +yamllint molecule/presets/your-preset.yml + +# Исправить ошибки +molecule validate +``` + +### Проблема: Ошибки в пресете + +**Симптомы:** +- Синтаксические ошибки +- Ошибки валидации + +**Решение:** +```bash +# Проверить синтаксис +yamllint molecule/presets/your-preset.yml + +# Проверить структуру +molecule validate + +# Исправить ошибки +molecule syntax +``` + +## Проблемы с отчетами + +### Проблема: HTML отчет не генерируется + +**Симптомы:** +- `File not found` +- Ошибки генерации отчета + +**Решение:** +```bash +# Проверить JSON файл +ls -la reports/ +cat reports/lab-health.json + +# Перезапустить верификацию +make lab-verify + +# Сгенерировать отчет +make lab-report +``` + +### Проблема: Отчет пустой + +**Симптомы:** +- Отчет не содержит данных +- Ошибки в JSON + +**Решение:** +```bash +# Проверить JSON +jq . reports/lab-health.json + +# Перезапустить тест +make lab-test + +# Проверить логи +make lab-verify +``` + +## Полезные команды для диагностики + +### Общие команды + +```bash +# Проверить статус системы +docker ps +docker images +docker network ls +docker volume ls + +# Проверить ресурсы +free -h +df -h +top + +# Проверить сеть +netstat -tulpn +ss -tulpn +``` + +### Команды для Kubernetes + +```bash +# Проверить кластеры +kind get clusters +kubectl config get-contexts + +# Проверить ресурсы +kubectl get nodes +kubectl get pods -A +kubectl get svc -A + +# Проверить события +kubectl get events --sort-by=.metadata.creationTimestamp +``` + +### Команды для Ansible + +```bash +# Проверить инвентарь +ansible-inventory --list +ansible all -m ping + +# Проверить playbook +ansible-playbook --syntax-check playbook.yml +ansible-playbook --check playbook.yml +``` + +## Получение помощи + +Если проблема не решается: + +1. **Проверьте логи:** + ```bash + docker logs + kubectl logs + ``` + +2. **Создайте issue:** + - Опишите проблему + - Приложите логи + - Укажите версии компонентов + +3. **Обратитесь к сообществу:** + - GitHub Discussions + - Discord/Slack каналы + - Форумы Ansible + +4. **Проверьте документацию:** + - [Основная документация](universal-lab.md) + - [Примеры использования](examples.md) + - [API Reference](api.md) diff --git a/README-UNIVERSAL-LAB.md b/docs/universal-lab.md similarity index 100% rename from README-UNIVERSAL-LAB.md rename to docs/universal-lab.md diff --git a/roles/README.md b/roles/README.md deleted file mode 100644 index 16c0551..0000000 --- a/roles/README.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -# Роли Ansible -Разместите ваши роли Ansible в этом каталоге