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
This commit is contained in:
420
docs/roles.md
Normal file
420
docs/roles.md
Normal file
@@ -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).
|
||||
Reference in New Issue
Block a user