DevOpsLab/docs/roles.md

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

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

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

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

```bash
make role create NAME=my-role
```

**Что происходит:**
1. **Запрашивается описание роли** - краткое описание функциональности
2. **Настраивается основной пакет** - имя пакета для установки
3. **Настраивается сервис** - имя сервиса для управления
4. **Выбираются платформы** - поддерживаемые ОС (ubuntu, centos, rhel)
5. **Указываются теги** - теги для Ansible Galaxy
6. **Создается универсальная структура роли** с поддержкой RHEL и Debian семейств
7. **Создается папка `playbooks/`** для playbooks роли

### Структура созданной роли

```
roles/my-role/
├── tasks/
│   ├── main.yml          # Основные задачи (универсальные)
│   ├── debian.yml        # Задачи для Debian/Ubuntu
│   └── redhat.yml        # Задачи для RHEL/CentOS
├── handlers/
│   └── main.yml          # Обработчики
├── templates/             # Шаблоны Jinja2
├── files/                 # Статические файлы
├── vars/
│   └── main.yml          # Переменные роли
├── defaults/
│   └── main.yml          # Переменные по умолчанию
├── meta/
│   └── main.yml          # Метаданные роли
├── tests/                 # Тесты роли
└── playbooks/            # Playbooks роли
    └── (создаются через make role playbook)
```

## Универсальные роли

### Принцип работы

Роли создаются **универсальными** для RHEL и Debian семейств:

1. **`tasks/main.yml`** - содержит общую логику и включает OS-специфичные задачи
2. **`tasks/debian.yml`** - задачи для Debian/Ubuntu (apt, systemd)
3. **`tasks/redhat.yml`** - задачи для RHEL/CentOS (yum, systemd)

### Автоматическое определение ОС

```yaml
# tasks/main.yml
- name: Include OS-specific tasks
  include_tasks: "{{ ansible_os_family | lower }}.yml"
```

**Поддерживаемые ОС:**
- **Debian семейство**: Ubuntu, Debian, Linux Mint
- **RHEL семейство**: CentOS, RHEL, Rocky Linux, AlmaLinux

### Примеры задач

#### Debian/Ubuntu (tasks/debian.yml)
```yaml
---
# Задачи для Debian/Ubuntu семейства

- name: Update apt cache (Debian)
  apt:
    update_cache: true
    cache_valid_time: 3600
  when: ansible_os_family == 'Debian'

- name: Install nginx package (Debian)
  apt:
    name: "{{ nginx_package | default('nginx') }}"
    state: present
  when: ansible_os_family == 'Debian'
```

#### RHEL/CentOS (tasks/redhat.yml)
```yaml
---
# Задачи для RHEL/CentOS семейства

- name: Update yum cache (RHEL)
  yum:
    update_cache: true
  when: ansible_os_family == 'RedHat'

- name: Install nginx package (RHEL)
  yum:
    name: "{{ nginx_package | default('nginx') }}"
    state: present
  when: ansible_os_family == 'RedHat'
```

## Управление 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
  gather_facts: true
  vars:
    # Переменные для роли my-role
    my_role_enabled: true

  pre_tasks:
    - name: Display OS information
      debug:
        msg: "OS Family: {{ ansible_os_family }}, OS: {{ ansible_distribution }} {{ ansible_distribution_version }}"

  roles:
    - role: my-role

  post_tasks:
    - name: Verify my-role installation
      debug:
        msg: "my-role successfully deployed on {{ inventory_hostname }}"
```

### Универсальные playbooks

Playbooks создаются **универсальными** с поддержкой:

1. **`gather_facts: true`** - сбор информации об ОС
2. **`pre_tasks`** - отображение информации об ОС
3. **`post_tasks`** - проверка успешного развертывания
4. **Переменные роли** - автоматически добавляются в `vars`

### Список 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. Универсальные роли
- **Всегда создавайте OS-специфичные задачи** в `debian.yml` и `redhat.yml`
- **Используйте `ansible_os_family`** для определения ОС
- **Тестируйте на разных платформах** (Ubuntu, CentOS, RHEL)
- **Используйте универсальные модули** когда возможно (package, systemd)

### 2. Структура роли
- **`tasks/main.yml`** - общая логика и включение OS-специфичных задач
- **`tasks/debian.yml`** - задачи для Debian/Ubuntu (apt, systemd)
- **`tasks/redhat.yml`** - задачи для RHEL/CentOS (yum, systemd)
- **`handlers`** - для перезапуска сервисов
- **`templates`** - для конфигурационных файлов
- **`files`** - для статических файлов

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

### 4. Playbooks
- **`gather_facts: true`** - всегда собирайте информацию об ОС
- **`pre_tasks`** - отображайте информацию об ОС
- **`post_tasks`** - проверяйте успешное развертывание
- **Используйте переменные** для настройки

### 5. Тестирование
- **`make role test`** - проверка роли
- **Тестируйте на разных ОС** - Ubuntu, CentOS, RHEL
- **Создавайте тесты** в папке 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