DevOpsLab/docs/roles.md

# Управление ролями Ansible

Полное руководство по созданию, управлению и использованию ролей в универсальной лаборатории.

## Создание роли

### Интерактивное создание

```bash
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
make role playbook NAME=my-role
# Выберите: create
# Введите имя: deploy
```

**Создается файл:** `roles/my-role/playbooks/deploy.yml`

```yaml
---
# Playbook: deploy для роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

- name: deploy
  hosts: all
  become: true
  roles:
    - role: my-role
```

### Список playbooks

```bash
make role playbook NAME=my-role
# Выберите: list
```

### Редактирование 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/

### 2. Переменные
- **defaults/main.yml** - значения по умолчанию
- **vars/main.yml** - внутренние переменные роли
- Используйте **префиксы** для переменных роли

### 3. Playbooks
- Создавайте **отдельные playbooks** для разных сценариев
- Используйте **переменные** для настройки
- Добавляйте **проверки** и **валидацию**

### 4. Тестирование
- Используйте **make role test** для проверки
- Создавайте **тесты** в папке tests/
- Проверяйте **разные платформы**

## Интеграция с лабораторией

### Автоматическое добавление в систему

При создании роли через `make role create`:
1. Роль автоматически добавляется в `deploy/tasks/main.yml`
2. Создается переменная `{role_name}_enabled: true`
3. Обновляется `site.yml` с новой ролью

### Использование в playbooks

```yaml
---
- name: Deploy my-role
  hosts: all
  become: true
  roles:
    - role: my-role
      vars:
        my_role_enabled: true
        my_role_package: custom-package
```

## Автор

Сергей Антропов  
Сайт: https://devops.org.ru