diff --git a/docs/creating-roles.md b/docs/creating-roles.md index 44060c4..a62a3fd 100644 --- a/docs/creating-roles.md +++ b/docs/creating-roles.md @@ -1,7 +1,8 @@ # Создание и разработка ролей для AnsibleLab **Автор:** Сергей Антропов -**Сайт:** https://devops.org.ru +**Сайт:** https://devops.org.ru +**Версия:** 2.0.0 ## 🚀 Быстрый старт @@ -56,6 +57,7 @@ roles/my-role/ ```bash # Интерактивное создание роли make role create +# Введите имя роли: my-role # Система автоматически: # - Создаст структуру папок @@ -75,6 +77,8 @@ touch roles/my-role/{tasks,handlers,meta}/main.yml touch roles/my-role/defaults/main.yml touch roles/my-role/vars/main.yml touch roles/my-role/README.md + +# Добавление роли в roles/deploy.yml вручную ``` ## 📝 Разработка роли @@ -532,78 +536,3 @@ MIT ## Автор Сергей Антропов - https://devops.org.ru -``` - -## 🚀 Полный цикл разработки - -### 1. Создание роли - -```bash -# Создание структуры -mkdir -p roles/my-role/{tasks,handlers,templates,files,vars,defaults,meta} -touch roles/my-role/{tasks,handlers,meta}/main.yml -touch roles/my-role/defaults/main.yml -touch roles/my-role/vars/main.yml -touch roles/my-role/README.md -``` - -### 2. Разработка - -```bash -# Редактирование файлов роли -nano roles/my-role/tasks/main.yml -nano roles/my-role/defaults/main.yml -# ... остальные файлы -``` - -### 3. Тестирование - -```bash -# Lint проверка -make role lint - -# Тестирование в Docker -make role test minimal - -# Тестирование с custom preset -make role test my-custom-preset -``` - -### 4. Развертывание - -```bash -# Тестирование на реальных серверах -make role deploy - -# Развертывание на продакшн -make role deploy -# Подтвердить развертывание: y -``` - -## 🔧 Лучшие практики - -### 1. Структура кода - -- **Используйте теги** для группировки задач -- **Добавляйте условия** для условного выполнения -- **Используйте обработчики** для перезапуска сервисов -- **Документируйте переменные** в defaults/main.yml - -### 2. Безопасность - -- **Используйте vault** для секретов -- **Проверяйте права** пользователей -- **Настраивайте файрвол** при необходимости -- **Используйте SSL** для защищенных соединений - -### 3. Производительность - -- **Используйте кеширование** для повторных операций -- **Оптимизируйте пакеты** для уменьшения размера -- **Используйте параллельное выполнение** где возможно -- **Мониторьте ресурсы** системы - ---- - -**Автор:** Сергей Антропов -**Сайт:** https://devops.org.ru diff --git a/docs/examples.md b/docs/examples.md index 3567620..b02bb59 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,425 +1,325 @@ -# Примеры использования универсальной системы тестирования +# Примеры использования AnsibleLab -## Пример 1: Тестирование кластера etcd + PostgreSQL + Patroni +**Автор:** Сергей Антропов +**Сайт:** https://devops.org.ru +**Версия:** 2.0.0 -### Описание -Этот пример демонстрирует тестирование высокодоступного кластера PostgreSQL с Patroni и etcd. +## Быстрый старт -### Preset: etcd-patroni - -```yaml -# molecule/presets/etcd-patroni.yml -hosts: - # ETCD кластер (5 узлов для высокой доступности) - - name: etcd1 - family: debian - groups: [etcd, cluster] - - name: etcd2 - family: rhel - groups: [etcd, cluster] - - name: etcd3 - family: debian - groups: [etcd, cluster] - - name: etcd4 - family: rhel - groups: [etcd, cluster] - - name: etcd5 - family: debian - groups: [etcd, cluster] - - # Patroni кластер (3 узла PostgreSQL) - - name: patroni1 - family: rhel - groups: [patroni, database, cluster] - - name: patroni2 - family: debian - groups: [patroni, database, cluster] - - name: patroni3 - family: rhel - groups: [patroni, database, cluster] - - # HAProxy для балансировки - - name: haproxy - family: debian - groups: [haproxy, loadbalancer] - publish: ["5000:5000", "5001:5001"] # RW и RO порты - - # DinD узел для тестирования Docker Compose внутри - - name: app-dind - type: dind - groups: [apps, docker] - publish: ["8080:8080"] -``` - -### Запуск тестирования +### Базовое тестирование роли ```bash -# Информация о preset'е -make preset-info PRESET=etcd-patroni +# Тестирование роли ping с minimal preset (1 хост) +make role test minimal -# Тестирование с preset'ом -make preset-test PRESET=etcd-patroni +# Тестирование роли docker с default preset (2 хоста) +make role lint docker +make role test docker +``` -# Или через role test -make role test etcd-patroni +### Просмотр доступных preset'ов + +```bash +# Список всех preset'ов +make presets list + +# Информация о конкретном preset'е +make presets info PRESET=default +make presets info PRESET=all-images +``` + +## Пример 1: Тестирование роли Docker + +### Описание +Тестирование универсальной роли Docker на разных ОС. + +```bash +# Lint проверка +make role lint docker + +# Тестирование с minimal preset (1 хост Debian) +make role test minimal + +# Тестирование с default preset (Ubuntu + Debian) +make role test default + +# Тестирование с preset all-images (16 хостов, все ОС) +make role test all-images ``` ### Проверка результатов ```bash -# Проверить статус контейнеров -make container-info +# Просмотр созданных контейнеров +docker ps -a --filter "network=labnet" -# Проверить vault файлы -make vault-check +# Просмотр логов контейнера +docker logs $(docker ps -aq --filter "network=labnet" | head -1) + +# Вход в контейнер для проверки +docker exec -it $(docker ps -aq --filter "network=labnet" | head -1) bash ``` -## Пример 2: Нагрузочное тестирование +## Пример 2: Создание собственной роли -### Описание -Этот пример демонстрирует тестирование под нагрузкой с множественными серверами и кэшем. +### Создание роли -### Preset: performance +```bash +# Интерактивное создание новой роли +make role create +# Введите имя роли: nginx +# Редактирование роли +cd roles/nginx +nano tasks/main.yml +``` + +### Разработка роли + +**`roles/nginx/tasks/main.yml`:** ```yaml -# molecule/presets/performance.yml -hosts: - # Основные серверы (5 узлов) - - name: server1 - family: debian - groups: [servers, web, app] - - name: server2 - family: rhel - groups: [servers, web, app] - - name: server3 - family: debian - groups: [servers, web, app] - - name: server4 - family: rhel - groups: [servers, web, app] - - name: server5 - family: debian - groups: [servers, web, app] - - # База данных (3 узла) - - name: db1 - family: rhel - groups: [database, db] - - name: db2 - family: debian - groups: [database, db] - - name: db3 - family: rhel - groups: [database, db] - - # Кэш (3 узла Redis) - - name: cache1 - family: debian - groups: [cache, redis] - - name: cache2 - family: rhel - groups: [cache, redis] - - name: cache3 - family: debian - groups: [cache, redis] - - # Load balancer - - name: lb1 - family: rhel - groups: [loadbalancer, haproxy] - publish: ["80:80", "443:443"] - - # DinD узел для тестирования Docker Compose - - name: compose-dind - type: dind - groups: [apps, docker] - publish: ["8080:8080", "8081:8081"] -``` - -### Запуск тестирования - -```bash -# Тестирование с performance preset'ом -make role test performance - -# Проверка статуса -make container-info -``` - -## Пример 3: Тестирование безопасности - -### Описание -Этот пример демонстрирует тестирование в безопасной среде с bastion хостами и изоляцией. - -### Preset: security - -```yaml -# molecule/presets/security.yml -hosts: - # Bastion хосты (точки входа) - - name: bastion1 - family: rhel - groups: [bastion, security, jump] - publish: ["2222:22"] - - name: bastion2 - family: debian - groups: [bastion, security, jump] - publish: ["2223:22"] - - # Внутренние серверы (без внешнего доступа) - - name: internal1 - family: rhel - groups: [internal, servers, app] - - name: internal2 - family: debian - groups: [internal, servers, app] - - name: internal3 - family: rhel - groups: [internal, servers, app] - - # База данных (изолированная сеть) - - name: db-secure1 - family: rhel - groups: [database, secure, internal] - - name: db-secure2 - family: debian - groups: [database, secure, internal] - - # Мониторинг и логирование - - name: monitor1 - family: debian - groups: [monitoring, security, logs] - - name: monitor2 - family: rhel - groups: [monitoring, security, logs] - - # Firewall и сетевые компоненты - - name: fw1 - family: rhel - groups: [firewall, network, security] - - name: fw2 - family: debian - groups: [firewall, network, security] - - # DOoD узел для тестирования Docker безопасности - - name: docker-secure - type: dood - family: debian - groups: [docker, security, apps] - publish: ["8080:8080"] - env: - DOCKER_HOST: "unix:///var/run/docker.sock" -``` - -### Запуск тестирования - -```bash -# Тестирование с security preset'ом -make role test security - -# Проверка безопасности -make vault-check -make vault-scan -``` - -## Пример 4: Тестирование на разных ОС - -### Описание -Этот пример демонстрирует тестирование на различных операционных системах. - -### Preset: multi-os - -```yaml -# molecule/presets/multi-os.yml -hosts: - # Debian/Ubuntu серверы - - name: ubuntu1 - family: ubuntu - groups: [ubuntu, servers, web] - - name: debian1 - family: debian - groups: [debian, servers, web] - - name: ubuntu2 - family: ubuntu - groups: [ubuntu, servers, app] - - name: debian2 - family: debian - groups: [debian, servers, app] - - # RHEL/CentOS серверы - - name: rhel1 - family: rhel - groups: [rhel, servers, web] - - name: centos1 - family: centos - groups: [centos, servers, web] - - name: rhel2 - family: rhel - groups: [rhel, servers, app] - - name: centos2 - family: centos - groups: [centos, servers, app] - - # База данных на разных ОС - - name: db-ubuntu - family: ubuntu - groups: [database, ubuntu, db] - - name: db-rhel - family: rhel - groups: [database, rhel, db] - - # Load balancer - - name: lb-mixed - family: debian - groups: [loadbalancer, haproxy] - publish: ["80:80", "443:443"] - - # DinD узел для тестирования Docker - - name: docker-mixed - type: dind - groups: [docker, apps] - publish: ["8080:8080"] -``` - -### Запуск тестирования - -```bash -# Тестирование с multi-os preset'ом -make role test multi-os - -# Проверка типов контейнеров -make container-types -``` - -## Пример 5: Создание собственного preset'а - -### Описание -Этот пример демонстрирует создание собственного preset'а для специфических нужд. - -### Создание preset'а - -```bash -# Создать новый preset -cat > molecule/presets/my-custom.yml << 'EOF' --- -# Пресет для тестирования веб-приложения -# Автор: Ваше имя -# Сайт: https://your-site.com +- name: Установка nginx + package: + name: nginx + state: present + when: ansible_os_family in ['Debian', 'RedHat'] -docker_network: labnet -generated_inventory: "{{ molecule_ephemeral_directory }}/inventory/hosts.ini" - -# systemd-ready образы -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: web1 - family: debian - groups: [web, servers] - publish: ["80:80", "443:443"] - - name: web2 - family: rhel - groups: [web, servers] - publish: ["8080:80", "8443:443"] - - # База данных - - name: db1 - family: rhel - groups: [database, db] - - name: db2 - family: debian - groups: [database, db] - - # Кэш - - name: cache1 - family: debian - groups: [cache, redis] - - # DinD узел для тестирования - - name: app-dind - type: dind - groups: [apps, docker] - publish: ["8080:8080"] -EOF +- name: Запуск nginx + systemd: + name: nginx + state: started + enabled: yes ``` -### Использование preset'а +### Тестирование роли ```bash -# Информация о preset'е -make preset-info PRESET=my-custom +# Lint проверка +make role lint nginx -# Тестирование с preset'ом -make preset-test PRESET=my-custom +# Тестирование с minimal preset +make role test minimal -# Или через role test -make role test my-custom +# Проверка работы nginx +docker exec -it $(docker ps -aq --filter "network=labnet" | head -1) systemctl status nginx ``` -## Пример 6: Работа с Ansible Vault +## Пример 3: Использование preset'ов -### Создание vault файла +### Minimal preset (1 хост) ```bash -# Создать файл секретов +# Быстрое тестирование на 1 хосте +make role test minimal + +# Проверка контейнера +docker ps -a --filter "network=labnet" +``` + +### Default preset (2 хоста) + +```bash +# Тестирование на Ubuntu + Debian +make role test default + +# Проверка нескольких контейнеров +docker ps -a --filter "network=labnet" +``` + +### All-images preset (16 хостов) + +```bash +# Полное тестирование всех ОС +make role test all-images + +# Проверка всех контейнеров +docker ps -a --filter "network=labnet" --format "table {{.Names}}\t{{.Status}}" +``` + +### Preset'ы по ОС + +```bash +# Тестирование на всех версиях Ubuntu +make role test ubuntu-all + +# Тестирование на всех версиях Debian +make role test debian-all + +# Тестирование на всех версиях CentOS +make role test centos-all +``` + +## Пример 4: Работа с Ansible Vault + +### Создание секретов + +```bash +# Инициализация vault +make vault init + +# Создание нового файла секретов make vault create - -# Ввести имя файла: secrets -# Ввести содержимое: -# --- -# database_password: "super_secret_password" -# api_key: "your_api_key_here" -# ssl_cert: "your_ssl_certificate" +# Имя файла: secrets ``` -### Использование в ролях +### Редактирование секретов + +```bash +# Редактирование +make vault edit +# Имя файла: secrets + +# Просмотр секретов +make vault show +# Имя файла: secrets +``` + +### Использование в тестировании + +Секреты автоматически расшифровываются при запуске тестов и шифруются обратно после завершения. + +## Пример 5: CI/CD интеграция + +### GitHub Actions ```yaml -# roles/my-role/tasks/main.yml -- name: Configure database - template: - src: database.conf.j2 - dest: /etc/database.conf - vars: - db_password: "{{ database_password }}" - api_key: "{{ api_key }}" +name: Ansible Tests +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run tests + run: | + make role lint + make role test minimal ``` -### Проверка безопасности +### GitLab CI + +```yaml +test: + script: + - make role lint + - make role test minimal + only: + - merge_requests + - main +``` + +## Пример 6: Диагностика и отладка + +### Проверка линтинга ```bash -# Проверить vault файлы -make vault-check +# Линт всех ролей +make role lint -# Найти потенциальные секреты -make vault-scan +# Линт конкретной роли +make role lint docker + +# Линт с подробным выводом +ansible-lint roles/docker/ -vv +``` + +### Диагностика тестов + +```bash +# Проверка preset'ов +make presets list +make presets info PRESET=default + +# Проверка контейнеров +docker ps -a --filter "network=labnet" +docker network inspect labnet + +# Просмотр логов +docker logs -f $(docker ps -aq --filter "network=labnet" | head -1) +``` + +### Очистка + +```bash +# Очистка контейнеров Molecule +make clean-containers + +# Очистка образов +make docker clean + +# Полная очистка +make docker purge +``` + +## Полезные команды + +### Просмотр информации + +```bash +# Список всех ролей +make role list + +# Список preset'ов +make presets list + +# Информация об образах +make docker info + +# Справка по командам +make help +``` + +### Docker операции + +```bash +# Проверка builder'а +make docker check-builder + +# Диагностика buildx +make docker diagnose + +# Настройка builder'а +make docker setup-builder + +# Пересборка образов +make docker rebuild +``` + +### Vault операции + +```bash +# Создание vault +make vault init + +# Работа с секретами +make vault create +make vault edit +make vault show + +# Проверка vault +make vault check ``` ## Заключение -Эти примеры демонстрируют различные способы использования универсальной системы тестирования Ansible ролей. Вы можете: +Эти примеры демонстрируют основные возможности AnsibleLab: -1. Использовать готовые preset'ы для быстрого тестирования -2. Создавать собственные preset'ы для специфических нужд -3. Комбинировать различные типы контейнеров -4. Использовать Ansible Vault для безопасности -5. Тестировать на различных операционных системах +1. **Быстрое тестирование** с minimal preset +2. **Полное тестирование** с all-images preset +3. **Создание ролей** через интерактивные команды +4. **Работа с Vault** для секретов +5. **Диагностика** и отладка тестов +6. **Интеграция CI/CD** для автоматизации -Для получения дополнительной информации используйте: -- `make help` - общая справка -- `make preset-list` - список preset'ов -- `make container-types` - типы контейнеров -- `make vault` - команды Vault +Для получения дополнительной информации: +- Используйте `make help` для списка команд +- Читайте документацию в `docs/` директории +- Изучайте примеры в `roles/docker/` + +--- + +**Автор:** Сергей Антропов +**Сайт:** https://devops.org.ru