DevOpsLab/docs/creating-roles.md

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

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

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

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

# Просмотр всех ролей
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        # Документация роли

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

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

# Интерактивное создание роли
make role create

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

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

# Создание директории роли
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

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

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

---
# Основные задачи для роли 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)

---
# Обработчики для роли 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)

---
# Переменные по умолчанию для роли 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)

---
# Переменные роли 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)

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

galaxy_info:
  author: Сергей Антропов
  description: Моя кастомная роль для AnsibleTemplate
  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:

# Конфигурация 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:

[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:

[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 проверка

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

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

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

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

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

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

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

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

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

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

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

Роль автоматически включается в:

• molecule/default/site.yml (для тестирования)
• roles/deploy.yml (для продакшн развертывания)

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

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

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

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

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

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

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

README.md для роли

# Роль 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

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

- 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

---
- 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

## 🚀 Полный цикл разработки

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

```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

2. Разработка

# Редактирование файлов роли
nano roles/my-role/tasks/main.yml
nano roles/my-role/defaults/main.yml
# ... остальные файлы

3. Тестирование

# Lint проверка
make role lint

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

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

4. Развертывание

# Тестирование на реальных серверах
make role deploy

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

🔧 Лучшие практики

1. Структура кода

• Используйте теги для группировки задач
• Добавляйте условия для условного выполнения
• Используйте обработчики для перезапуска сервисов
• Документируйте переменные в defaults/main.yml

2. Безопасность

• Используйте vault для секретов
• Проверяйте права пользователей
• Настраивайте файрвол при необходимости
• Используйте SSL для защищенных соединений

3. Производительность

• Используйте кеширование для повторных операций
• Оптимизируйте пакеты для уменьшения размера
• Используйте параллельное выполнение где возможно
• Мониторьте ресурсы системы

---

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