feat: Добавлена интерактивность и поддержка playbooks для ролей
- Улучшена команда make role create с интерактивным вводом - Добавлена команда make role playbook для управления playbooks - Создана папка playbooks/ в структуре роли - Обновлена документация по работе с ролями Новые возможности: - Интерактивное создание роли с настройкой параметров - Управление playbooks роли (create|list|edit|run) - Автоматическое создание структуры с папкой playbooks - Улучшенные метаданные роли с платформами и тегами Интерактивные параметры при создании роли: - Описание роли - Основной пакет - Сервис - Платформы (ubuntu,centos,rhel) - Теги для Ansible Galaxy Команды playbooks: - make role playbook NAME=my-role create - создать playbook - make role playbook NAME=my-role list - список playbooks - make role playbook NAME=my-role edit - редактировать playbook - make role playbook NAME=my-role run - запустить playbook Документация: - Создан docs/roles.md с полным руководством - Обновлен README.md с новыми командами - Добавлены примеры использования Преимущества: - Полная интерактивность при создании ролей - Удобное управление playbooks роли - Автоматическая генерация структуры - Подробная документация - Интеграция с лабораторией Автор: Сергей Антропов Сайт: https://devops.org.ru
This commit is contained in:
612
docs/roles.md
612
docs/roles.md
@@ -1,420 +1,276 @@
|
||||
# Ansible Роли
|
||||
# Управление ролями 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/
|
||||
make role create NAME=my-role
|
||||
```
|
||||
|
||||
### Ручное создание
|
||||
**Что происходит:**
|
||||
1. **Запрашивается описание роли** - краткое описание функциональности
|
||||
2. **Настраивается основной пакет** - имя пакета для установки
|
||||
3. **Настраивается сервис** - имя сервиса для управления
|
||||
4. **Выбираются платформы** - поддерживаемые ОС (ubuntu, centos, rhel)
|
||||
5. **Указываются теги** - теги для Ansible Galaxy
|
||||
6. **Создается структура роли** с папкой `playbooks/`
|
||||
|
||||
### Структура созданной роли
|
||||
|
||||
```
|
||||
roles/my-role/
|
||||
├── tasks/
|
||||
│ └── main.yml # Основные задачи
|
||||
├── handlers/
|
||||
│ └── main.yml # Обработчики
|
||||
├── templates/ # Шаблоны Jinja2
|
||||
├── files/ # Статические файлы
|
||||
├── vars/
|
||||
│ └── main.yml # Переменные роли
|
||||
├── defaults/
|
||||
│ └── main.yml # Переменные по умолчанию
|
||||
├── meta/
|
||||
│ └── main.yml # Метаданные роли
|
||||
├── tests/ # Тесты роли
|
||||
└── playbooks/ # Playbooks роли
|
||||
└── (создаются через make role playbook)
|
||||
```
|
||||
|
||||
## Управление playbooks роли
|
||||
|
||||
### Создание playbook
|
||||
|
||||
```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
|
||||
make role playbook NAME=my-role
|
||||
# Выберите: create
|
||||
# Введите имя: deploy
|
||||
```
|
||||
|
||||
## Использование роли
|
||||
|
||||
### В playbook
|
||||
**Создается файл:** `roles/my-role/playbooks/deploy.yml`
|
||||
|
||||
```yaml
|
||||
---
|
||||
- name: Deploy web server
|
||||
hosts: webservers
|
||||
become: true
|
||||
roles:
|
||||
- your_role
|
||||
```
|
||||
# Playbook: deploy для роли my-role
|
||||
# Автор: Сергей Антропов
|
||||
# Сайт: https://devops.org.ru
|
||||
|
||||
### С переменными
|
||||
|
||||
```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
|
||||
- name: deploy
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- your_role
|
||||
EOF
|
||||
|
||||
# Создать инвентарь для тестов
|
||||
cat > roles/your_role/tests/inventory << EOF
|
||||
[webservers]
|
||||
localhost ansible_connection=local
|
||||
EOF
|
||||
- role: my-role
|
||||
```
|
||||
|
||||
### Запуск тестов
|
||||
### Список playbooks
|
||||
|
||||
```bash
|
||||
# Запустить тест роли
|
||||
ansible-playbook -i roles/your_role/tests/inventory roles/your_role/tests/test.yml
|
||||
make role playbook NAME=my-role
|
||||
# Выберите: list
|
||||
```
|
||||
|
||||
# Запустить тест с Molecule
|
||||
molecule test
|
||||
### Редактирование playbook
|
||||
|
||||
```bash
|
||||
make role playbook NAME=my-role
|
||||
# Выберите: edit
|
||||
# Введите имя: deploy
|
||||
```
|
||||
|
||||
### Запуск playbook
|
||||
|
||||
```bash
|
||||
make role playbook NAME=my-role
|
||||
# Выберите: run
|
||||
# Введите имя: deploy
|
||||
```
|
||||
|
||||
## Команды управления ролями
|
||||
|
||||
### Основные команды
|
||||
|
||||
```bash
|
||||
# Список ролей
|
||||
make role list
|
||||
|
||||
# Создать роль (интерактивно)
|
||||
make role create NAME=my-role
|
||||
|
||||
# Редактировать роль
|
||||
make role edit NAME=my-role
|
||||
|
||||
# Тестировать роль
|
||||
make role test NAME=my-role
|
||||
|
||||
# Проверить синтаксис
|
||||
make role lint
|
||||
|
||||
# Развернуть роли
|
||||
make role deploy
|
||||
|
||||
# Информация о роли
|
||||
make role info NAME=my-role
|
||||
|
||||
# Управление playbooks
|
||||
make role playbook NAME=my-role
|
||||
```
|
||||
|
||||
### Интерактивные возможности
|
||||
|
||||
#### При создании роли:
|
||||
- **Описание роли** - автоматически добавляется в README.md
|
||||
- **Основной пакет** - настраивается в defaults/main.yml
|
||||
- **Сервис** - настраивается в defaults/main.yml
|
||||
- **Платформы** - добавляются в meta/main.yml
|
||||
- **Теги** - добавляются в meta/main.yml
|
||||
|
||||
#### При работе с playbooks:
|
||||
- **Создание** - интерактивный ввод имени
|
||||
- **Редактирование** - выбор из списка существующих
|
||||
- **Запуск** - выбор playbook для выполнения
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Создание роли nginx
|
||||
|
||||
```bash
|
||||
make role create NAME=nginx
|
||||
# Описание: Nginx web server role
|
||||
# Пакет: nginx
|
||||
# Сервис: nginx
|
||||
# Платформы: ubuntu,centos
|
||||
# Теги: web,nginx,server
|
||||
```
|
||||
|
||||
### Создание playbook для nginx
|
||||
|
||||
```bash
|
||||
make role playbook NAME=nginx
|
||||
# Выберите: create
|
||||
# Имя: install
|
||||
```
|
||||
|
||||
**Результат:** `roles/nginx/playbooks/install.yml`
|
||||
|
||||
### Запуск playbook
|
||||
|
||||
```bash
|
||||
make role playbook NAME=nginx
|
||||
# Выберите: run
|
||||
# Имя: install
|
||||
```
|
||||
|
||||
## Структура файлов роли
|
||||
|
||||
### tasks/main.yml
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Основные задачи роли nginx
|
||||
# Автор: Сергей Антропов
|
||||
# Сайт: https://devops.org.ru
|
||||
|
||||
- name: nginx placeholder
|
||||
debug:
|
||||
msg: "Роль nginx готова для настройки"
|
||||
|
||||
- name: Install nginx package
|
||||
package:
|
||||
name: "{{ nginx_package | default('nginx') }}"
|
||||
state: present
|
||||
|
||||
- name: Start nginx service
|
||||
systemd:
|
||||
name: "{{ nginx_service | default('nginx') }}"
|
||||
state: started
|
||||
enabled: true
|
||||
when: nginx_service is defined
|
||||
```
|
||||
|
||||
### defaults/main.yml
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Переменные по умолчанию для роли nginx
|
||||
# Автор: Сергей Антропов
|
||||
# Сайт: https://devops.org.ru
|
||||
|
||||
nginx_enabled: true
|
||||
nginx_package: nginx
|
||||
nginx_service: nginx
|
||||
```
|
||||
|
||||
### meta/main.yml
|
||||
|
||||
```yaml
|
||||
---
|
||||
galaxy_info:
|
||||
author: Сергей Антропов
|
||||
description: Nginx web server role
|
||||
company: https://devops.org.ru
|
||||
license: MIT
|
||||
min_ansible_version: 2.9
|
||||
platforms:
|
||||
- name: Ubuntu
|
||||
versions: [focal, jammy]
|
||||
- name: CentOS
|
||||
versions: [7, 8, 9]
|
||||
- name: RHEL
|
||||
versions: [7, 8, 9]
|
||||
galaxy_tags: [web,nginx,server]
|
||||
dependencies: []
|
||||
```
|
||||
|
||||
## Лучшие практики
|
||||
|
||||
### Структура задач
|
||||
### 1. Структура роли
|
||||
- Используйте **tasks/main.yml** для основных задач
|
||||
- Создавайте **отдельные файлы** для сложных задач
|
||||
- Используйте **handlers** для перезапуска сервисов
|
||||
- Храните **шаблоны** в templates/
|
||||
- Храните **статические файлы** в files/
|
||||
|
||||
```yaml
|
||||
---
|
||||
# tasks/main.yml
|
||||
- name: Install package
|
||||
package:
|
||||
name: "{{ package_name }}"
|
||||
state: present
|
||||
notify: restart service
|
||||
### 2. Переменные
|
||||
- **defaults/main.yml** - значения по умолчанию
|
||||
- **vars/main.yml** - внутренние переменные роли
|
||||
- Используйте **префиксы** для переменных роли
|
||||
|
||||
- name: Configure service
|
||||
template:
|
||||
src: config.j2
|
||||
dest: /etc/service/config.conf
|
||||
notify: restart service
|
||||
### 3. Playbooks
|
||||
- Создавайте **отдельные playbooks** для разных сценариев
|
||||
- Используйте **переменные** для настройки
|
||||
- Добавляйте **проверки** и **валидацию**
|
||||
|
||||
- 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
|
||||
```
|
||||
### 4. Тестирование
|
||||
- Используйте **make role test** для проверки
|
||||
- Создавайте **тесты** в папке tests/
|
||||
- Проверяйте **разные платформы**
|
||||
|
||||
## Интеграция с лабораторией
|
||||
|
||||
### Использование в пресетах
|
||||
### Автоматическое добавление в систему
|
||||
|
||||
При создании роли через `make role create`:
|
||||
1. Роль автоматически добавляется в `deploy/tasks/main.yml`
|
||||
2. Создается переменная `{role_name}_enabled: true`
|
||||
3. Обновляется `site.yml` с новой ролью
|
||||
|
||||
### Использование в playbooks
|
||||
|
||||
```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
|
||||
- name: Deploy my-role
|
||||
hosts: all
|
||||
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
|
||||
- role: my-role
|
||||
vars:
|
||||
my_role_enabled: true
|
||||
my_role_package: custom-package
|
||||
```
|
||||
|
||||
### Тестирование с различными пресетами
|
||||
## Автор
|
||||
|
||||
```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).
|
||||
Сергей Антропов
|
||||
Сайт: https://devops.org.ru
|
||||
Reference in New Issue
Block a user