feat: Полная переработка документации и структуры проекта
- Переписан главный README.md с подробной навигацией - Создана структурированная документация в docs/: - getting-started.md - быстрый старт - creating-roles.md - создание ролей - cicd-setup.md - настройка CI/CD - monitoring.md - мониторинг и диагностика - site-yml-guide.md - руководство по site.yml - molecule-guide.md - подробное руководство по Molecule - Переписан dockerfiles/README.md с детальным описанием всех образов - Перенесен deploy.yml из корня в roles/ для лучшей организации - Обновлен site.yml для импорта roles/deploy.yml - Добавлены fallback значения в create.yml для надежности - Созданы скрипты автоматизации: - update-playbooks.sh - обновление playbook'ов - generate-role-docs.sh - генерация документации - setup-cicd.sh - настройка CI/CD - Добавлен env.example с примерами переменных - Обновлен Makefile с новыми командами автоматизации - Улучшена навигация по документации
This commit is contained in:
Сергей Антропов
571
docs/creating-roles.md
Normal file
571
docs/creating-roles.md
Normal file
@@ -0,0 +1,571 @@
|
||||
# Создание и разработка ролей
|
||||
|
||||
**Автор:** Сергей Антропов
|
||||
**Сайт:** https://devops.org.ru
|
||||
|
||||
## 📁 Структура роли
|
||||
|
||||
### Стандартная структура
|
||||
|
||||
```
|
||||
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
|
||||
# Создание директории роли
|
||||
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)
|
||||
|
||||
```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: Моя кастомная роль для 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`:**
|
||||
```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
|
||||
```
|
||||
|
||||
## 🚀 Полный цикл разработки
|
||||
|
||||
### 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. Разработка
|
||||
|
||||
```bash
|
||||
# Редактирование файлов роли
|
||||
nano roles/my-role/tasks/main.yml
|
||||
nano roles/my-role/defaults/main.yml
|
||||
# ... остальные файлы
|
||||
```
|
||||
|
||||
### 3. Тестирование
|
||||
|
||||
```bash
|
||||
# Lint проверка
|
||||
make role lint
|
||||
|
||||
# Тестирование в Docker
|
||||
make role test minimal
|
||||
|
||||
# Тестирование с custom preset
|
||||
make role test my-custom-preset
|
||||
```
|
||||
|
||||
### 4. Развертывание
|
||||
|
||||
```bash
|
||||
# Тестирование на реальных серверах
|
||||
make role deploy
|
||||
|
||||
# Развертывание на продакшн
|
||||
make role deploy
|
||||
# Подтвердить развертывание: y
|
||||
```
|
||||
|
||||
## 🔧 Лучшие практики
|
||||
|
||||
### 1. Структура кода
|
||||
|
||||
- **Используйте теги** для группировки задач
|
||||
- **Добавляйте условия** для условного выполнения
|
||||
- **Используйте обработчики** для перезапуска сервисов
|
||||
- **Документируйте переменные** в defaults/main.yml
|
||||
|
||||
### 2. Безопасность
|
||||
|
||||
- **Используйте vault** для секретов
|
||||
- **Проверяйте права** пользователей
|
||||
- **Настраивайте файрвол** при необходимости
|
||||
- **Используйте SSL** для защищенных соединений
|
||||
|
||||
### 3. Производительность
|
||||
|
||||
- **Используйте кеширование** для повторных операций
|
||||
- **Оптимизируйте пакеты** для уменьшения размера
|
||||
- **Используйте параллельное выполнение** где возможно
|
||||
- **Мониторьте ресурсы** системы
|
||||
|
||||
---
|
||||
|
||||
**Автор:** Сергей Антропов
|
||||
**Сайт:** https://devops.org.ru
|
||||
Reference in New Issue
Block a user