DevOpsLab/docs/creating-roles.md

# Создание и разработка ролей для AnsibleLab

**Автор:** Сергей Антропов  
**Сайт:** https://devops.org.ru  
**Версия:** 3.0.0

## 🚀 Быстрый старт

### Интерактивное управление ролями

```bash
# Просмотр всех ролей
make role list

# Создание новой роли (интерактивно)
make role create

# Удаление роли (интерактивно)
make role delete
```

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

При создании или удалении роли система автоматически:
- ✅ Обновляет `roles/deploy.yml`
- ✅ Создает полную структуру папок
- ✅ Генерирует README.md с документацией
- ✅ Настраивает метаданные роли

## 📁 Структура роли

### Стандартная структура

```
roles/my-role/
├── tasks/           # Основные задачи
│   └── main.yml
├── handlers/        # Обработчики
│   └── main.yml
├── templates/       # Шаблоны Jinja2
│   └── my-role.conf.j2
├── files/           # Статические файлы
│   └── my-role.service
├── vars/            # Переменные роли
│   └── main.yml
├── defaults/        # Переменные по умолчанию
│   └── main.yml
├── meta/            # Метаданные роли
│   └── main.yml
└── README.md        # Документация роли
```

### Создание структуры

#### Автоматическое создание (рекомендуется)

```bash
# Интерактивное создание роли
make role create
# Введите имя роли: my-role

# Система автоматически:
# - Создаст структуру папок
# - Создаст все необходимые файлы
# - Обновит roles/deploy.yml
# - Создаст README.md с документацией
```

#### Ручное создание

```bash
# Создание директории роли
mkdir -p roles/my-role/{tasks,handlers,templates,files,vars,defaults,meta}

# Создание основных файлов
touch roles/my-role/{tasks,handlers,meta}/main.yml
touch roles/my-role/defaults/main.yml
touch roles/my-role/vars/main.yml
touch roles/my-role/README.md

# Добавление роли в roles/deploy.yml вручную
```

## 📝 Разработка роли

### 1. Основные задачи (tasks/main.yml)

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

- name: Установка пакетов
  package:
    name: "{{ my_role_packages }}"
    state: present
  when: my_role_enabled | default(true)
  tags:
    - my-role
    - install

- name: Создание пользователя
  user:
    name: "{{ my_role_user }}"
    system: "{{ my_role_system_user | default(false) }}"
    shell: "{{ my_role_shell | default('/bin/bash') }}"
    home: "{{ my_role_home | default('/home/' + my_role_user) }}"
  when: my_role_create_user | default(true)
  tags:
    - my-role
    - user

- name: Настройка конфигурации
  template:
    src: my-role.conf.j2
    dest: "{{ my_role_config_file }}"
    owner: "{{ my_role_user }}"
    group: "{{ my_role_group | default(my_role_user) }}"
    mode: '0644'
    backup: "{{ my_role_backup | default(true) }}"
  notify: restart my-role
  tags:
    - my-role
    - config

- name: Настройка сервиса
  systemd:
    name: "{{ my_role_service_name | default('my-role') }}"
    enabled: "{{ my_role_enabled | default(true) }}"
    state: "{{ 'started' if my_role_enabled | default(true) else 'stopped' }}"
    daemon_reload: true
  tags:
    - my-role
    - service

- name: Настройка файрвола
  firewalld:
    port: "{{ my_role_port | default('8080') }}/tcp"
    permanent: true
    state: "{{ 'enabled' if my_role_firewall | default(false) else 'disabled' }}"
    immediate: true
  when: my_role_firewall | default(false)
  tags:
    - my-role
    - firewall
```

### 2. Обработчики (handlers/main.yml)

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

- name: restart my-role
  systemd:
    name: "{{ my_role_service_name | default('my-role') }}"
    state: restarted
    daemon_reload: true
  when: my_role_enabled | default(true)

- name: reload my-role
  systemd:
    name: "{{ my_role_service_name | default('my-role') }}"
    state: reloaded
  when: my_role_enabled | default(true)

- name: stop my-role
  systemd:
    name: "{{ my_role_service_name | default('my-role') }}"
    state: stopped
  when: not my_role_enabled | default(true)
```

### 3. Переменные по умолчанию (defaults/main.yml)

```yaml
---
# Переменные по умолчанию для роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

# Основные настройки
my_role_enabled: true
my_role_user: my-role
my_role_group: my-role
my_role_system_user: false
my_role_shell: /bin/bash
my_role_home: "{{ '/home/' + my_role_user if not my_role_system_user else '/var/lib/' + my_role_user }}"

# Пакеты
my_role_packages:
  - nginx
  - curl
  - htop

# Конфигурация
my_role_config_file: /etc/my-role/my-role.conf
my_role_log_level: info
my_role_port: 8080
my_role_backup: true

# Сервис
my_role_service_name: my-role
my_role_create_user: true

# Безопасность
my_role_firewall: false
my_role_ssl_enabled: false
my_role_ssl_certificate: /etc/ssl/certs/my-role.crt
my_role_ssl_private_key: /etc/ssl/private/my-role.key
```

### 4. Переменные роли (vars/main.yml)

```yaml
---
# Переменные роли my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

# Системные переменные
my_role_system_packages:
  - python3
  - python3-pip
  - python3-venv

# Конфигурационные переменные
my_role_config_template: my-role.conf.j2
my_role_service_template: my-role.service.j2

# Пути
my_role_log_dir: /var/log/my-role
my_role_data_dir: /var/lib/my-role
my_role_cache_dir: /var/cache/my-role
```

### 5. Метаданные (meta/main.yml)

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

galaxy_info:
  author: Сергей Антропов
  description: Моя кастомная роль для AnsibleLab
  company: https://devops.org.ru
  license: MIT
  min_ansible_version: "2.9"
  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: Debian
      versions:
        - bullseye
        - bookworm
    - name: EL
      versions:
        - 7
        - 8
        - 9
    - name: CentOS
      versions:
        - 7
        - 8
        - 9
    - name: AlmaLinux
      versions:
        - 8
        - 9
    - name: Rocky
      versions:
        - 8
        - 9
  galaxy_tags:
    - system
    - configuration
    - my-role
    - web
    - service

dependencies:
  - role: geerlingguy.docker
    when: my_role_docker_enabled | default(false)
  - role: geerlingguy.kubernetes
    when: my_role_k8s_enabled | default(false)
```

### 6. Шаблоны (templates/)

**`templates/my-role.conf.j2`:**
```jinja2
# Конфигурация my-role
# Автор: Сергей Антропов
# Сайт: https://devops.org.ru

[main]
enabled = {{ my_role_enabled | default(true) }}
user = {{ my_role_user }}
group = {{ my_role_group | default(my_role_user) }}
log_level = {{ my_role_log_level | default('info') }}
port = {{ my_role_port | default(8080) }}

[logging]
log_file = {{ my_role_log_dir | default('/var/log/my-role') }}/my-role.log
log_level = {{ my_role_log_level | default('info') }}
max_size = {{ my_role_log_max_size | default('100M') }}
max_files = {{ my_role_log_max_files | default('5') }}

[security]
ssl_enabled = {{ my_role_ssl_enabled | default(false) }}
{% if my_role_ssl_enabled | default(false) %}
ssl_certificate = {{ my_role_ssl_certificate }}
ssl_private_key = {{ my_role_ssl_private_key }}
{% endif %}

[network]
host = {{ my_role_host | default('0.0.0.0') }}
port = {{ my_role_port | default(8080) }}
timeout = {{ my_role_timeout | default(30) }}

{% if my_role_web_config | default(false) %}
[web]
enabled = true
{% raw %}
{{ my_role_nginx_config }}
{% endraw %}
{% endif %}
```

**`templates/my-role.service.j2`:**
```ini
[Unit]
Description=My Role Service
After=network.target

[Service]
Type=simple
User={{ my_role_user }}
Group={{ my_role_group | default(my_role_user) }}
ExecStart=/usr/bin/my-role --config {{ my_role_config_file }}
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

### 7. Статические файлы (files/)

**`files/my-role.service`:**
```ini
[Unit]
Description=My Role Service
After=network.target

[Service]
Type=simple
User=my-role
Group=my-role
ExecStart=/usr/bin/my-role --config /etc/my-role/my-role.conf
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

## 🧪 Тестирование роли

### 1. Lint проверка

```bash
# Lint проверка роли
make role lint

# Lint проверка конкретной роли
ansible-lint roles/my-role/
```

### 2. Тестирование в Docker

```bash
# Тестирование с default preset
make role test

# Тестирование с minimal preset
make role test minimal

# Тестирование с custom preset
make role test my-custom-preset
```

### 3. Тестирование на реальных серверах

```bash
# Dry-run развертывания
make role deploy

# Развертывание на продакшн
make role deploy
# Подтвердить развертывание: y
```

## 🔧 Интеграция с системой

### 1. Автоматическое включение в playbook'и

Роль автоматически включается в:
- `molecule/default/site.yml` (для тестирования)
- `roles/deploy.yml` (для продакшн развертывания)

### 2. Обновление playbook'ов

```bash
# Автоматическое обновление playbook'ов
make update-playbooks

# Проверка обновленных playbook'ов
make role test
```

### 3. Создание документации

```bash
# Автоматическое создание документации
make generate-docs

# Проверка созданной документации
ls -la roles/*/README.md
```

## 📚 Документация роли

### README.md для роли

```markdown
# Роль My-Role

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

## Описание

Роль для настройки и конфигурации my-role сервиса.

## Требования

- Ansible >= 2.9
- Поддерживаемые ОС: Ubuntu, Debian, RHEL, CentOS, AlmaLinux, Rocky Linux

## Переменные

| Переменная | Тип | По умолчанию | Описание |
|------------|-----|--------------|----------|
| `my_role_enabled` | boolean | `true` | Включить роль |
| `my_role_user` | string | `my-role` | Пользователь для сервиса |
| `my_role_packages` | list | `['nginx', 'curl']` | Пакеты для установки |
| `my_role_port` | integer | `8080` | Порт сервиса |
| `my_role_ssl_enabled` | boolean | `false` | Включить SSL |

## Примеры использования

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

```yaml
- name: Настройка my-role
  hosts: all
  roles:
    - my-role
```

### С кастомными параметрами

```yaml
- name: Настройка my-role с SSL
  hosts: all
  roles:
    - role: my-role
      vars:
        my_role_ssl_enabled: true
        my_role_port: 8443
        my_role_packages:
          - nginx
          - openssl
```

### В playbook

```yaml
---
- name: Настройка web серверов
  hosts: web_servers
  become: true
  roles:
    - role: my-role
      vars:
        my_role_enabled: true
        my_role_ssl_enabled: true
        my_role_firewall: true
  tags:
    - web
    - my-role
```

## Tags

- `my-role` - выполнение всех задач роли
- `install` - установка пакетов
- `user` - создание пользователя
- `config` - настройка конфигурации
- `service` - управление сервисом
- `firewall` - настройка файрвола

## Поддерживаемые ОС

- Red Hat Enterprise Linux 7/8/9
- CentOS 7/8/Stream
- AlmaLinux 8/9
- Rocky Linux 8/9
- Ubuntu 20.04/22.04
- Debian 10/11/12

## Лицензия

MIT

## Автор

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