DevOpsLab/docs/roles.md

# 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).