docs: Добавлена полная документация по кастомизации deploy.yml
- Создан файл docs/deploy-yml-customization.md с полным руководством - Добавлены примеры использования become, групп, переменных, тегов - Показаны примеры условного выполнения и параллелизма - Добавлены примеры обработки ошибок и безопасности - Включены примеры использования Vault и отладки - Добавлены лучшие практики и рекомендации - Обновлен roles/deploy.yml с примерами кастомизации - Добавлены ссылки на документацию в Makefile и README.md Документация включает: - 15 разделов с подробными примерами - Команды запуска с различными параметрами - Примеры продакшн развертывания - Настройки безопасности и мониторинга - Обработка ошибок и логирование
This commit is contained in:
Сергей Антропов
520
docs/deploy-yml-customization.md
Normal file
520
docs/deploy-yml-customization.md
Normal file
@@ -0,0 +1,520 @@
|
||||
# Кастомизация deploy.yml - Полное руководство
|
||||
|
||||
## Описание
|
||||
|
||||
Файл `roles/deploy.yml` - это основной playbook для развертывания Ansible ролей на продакшн серверах. Этот документ содержит полную сводку по кастомизации и настройке различных сценариев развертывания.
|
||||
|
||||
## Базовый пример
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Playbook для развертывания на продакшн серверах
|
||||
# Автор: Сергей Антропов
|
||||
# Сайт: https://devops.org.ru
|
||||
|
||||
- name: Развертывание всех ролей
|
||||
hosts: all
|
||||
roles:
|
||||
- ping
|
||||
```
|
||||
|
||||
## 1. Управление привилегиями (become)
|
||||
|
||||
### Базовое использование become
|
||||
```yaml
|
||||
- name: Развертывание с sudo правами
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
```
|
||||
|
||||
### Become с паролем
|
||||
```yaml
|
||||
- name: Развертывание с sudo паролем
|
||||
hosts: all
|
||||
become: true
|
||||
become_method: sudo
|
||||
become_user: root
|
||||
vars:
|
||||
ansible_become_pass: "{{ vault_sudo_password }}"
|
||||
roles:
|
||||
- nginx
|
||||
```
|
||||
|
||||
### Become для конкретных ролей
|
||||
```yaml
|
||||
- name: Развертывание с разными привилегиями
|
||||
hosts: all
|
||||
roles:
|
||||
- role: nginx
|
||||
become: true
|
||||
- role: app-config
|
||||
become: false
|
||||
```
|
||||
|
||||
## 2. Группировка хостов
|
||||
|
||||
### Развертывание по группам
|
||||
```yaml
|
||||
- name: Развертывание на веб-серверах
|
||||
hosts: webservers
|
||||
become: true
|
||||
roles:
|
||||
- nginx
|
||||
- php-fpm
|
||||
|
||||
- name: Развертывание на БД серверах
|
||||
hosts: databases
|
||||
become: true
|
||||
roles:
|
||||
- postgresql
|
||||
- redis
|
||||
|
||||
- name: Развертывание на мониторинг серверах
|
||||
hosts: monitoring
|
||||
become: true
|
||||
roles:
|
||||
- prometheus
|
||||
- grafana
|
||||
```
|
||||
|
||||
### Условное развертывание
|
||||
```yaml
|
||||
- name: Развертывание на production
|
||||
hosts: production
|
||||
become: true
|
||||
when: environment == "production"
|
||||
roles:
|
||||
- nginx
|
||||
- ssl-certificates
|
||||
|
||||
- name: Развертывание на staging
|
||||
hosts: staging
|
||||
become: false
|
||||
when: environment == "staging"
|
||||
roles:
|
||||
- nginx
|
||||
```
|
||||
|
||||
## 3. Переменные и конфигурация
|
||||
|
||||
### Глобальные переменные
|
||||
```yaml
|
||||
- name: Развертывание с переменными
|
||||
hosts: all
|
||||
become: true
|
||||
vars:
|
||||
nginx_port: 80
|
||||
nginx_ssl_port: 443
|
||||
app_name: "my-application"
|
||||
app_version: "1.0.0"
|
||||
roles:
|
||||
- nginx
|
||||
- application
|
||||
```
|
||||
|
||||
### Переменные для конкретных ролей
|
||||
```yaml
|
||||
- name: Развертывание с ролевыми переменными
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- role: nginx
|
||||
vars:
|
||||
nginx_port: 80
|
||||
nginx_ssl_enabled: true
|
||||
- role: postgresql
|
||||
vars:
|
||||
postgresql_version: "13"
|
||||
postgresql_max_connections: 200
|
||||
```
|
||||
|
||||
### Использование group_vars и host_vars
|
||||
```yaml
|
||||
# group_vars/webservers.yml
|
||||
nginx_worker_processes: 4
|
||||
nginx_worker_connections: 1024
|
||||
|
||||
# group_vars/databases.yml
|
||||
postgresql_shared_buffers: "256MB"
|
||||
postgresql_effective_cache_size: "1GB"
|
||||
|
||||
# В deploy.yml
|
||||
- name: Развертывание с групповыми переменными
|
||||
hosts: webservers:databases
|
||||
become: true
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
```
|
||||
|
||||
## 4. Теги (Tags)
|
||||
|
||||
### Базовое использование тегов
|
||||
```yaml
|
||||
- name: Развертывание с тегами
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- role: nginx
|
||||
tags: ['web', 'nginx']
|
||||
- role: postgresql
|
||||
tags: ['database', 'postgresql']
|
||||
- role: monitoring
|
||||
tags: ['monitoring', 'prometheus']
|
||||
```
|
||||
|
||||
### Запуск с тегами
|
||||
```bash
|
||||
# Развертывание только веб-серверов
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --tags web
|
||||
|
||||
# Развертывание только БД
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --tags database
|
||||
|
||||
# Развертывание веб + БД
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --tags web,database
|
||||
|
||||
# Пропустить мониторинг
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --skip-tags monitoring
|
||||
```
|
||||
|
||||
## 5. Обработчики (Handlers)
|
||||
|
||||
### Использование обработчиков
|
||||
```yaml
|
||||
- name: Развертывание с обработчиками
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
handlers:
|
||||
- name: restart nginx
|
||||
service:
|
||||
name: nginx
|
||||
state: restarted
|
||||
listen: "restart nginx"
|
||||
|
||||
- name: restart postgresql
|
||||
service:
|
||||
name: postgresql
|
||||
state: restarted
|
||||
listen: "restart postgresql"
|
||||
```
|
||||
|
||||
## 6. Условное выполнение
|
||||
|
||||
### Условия на основе переменных
|
||||
```yaml
|
||||
- name: Развертывание с условиями
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- role: nginx
|
||||
when: nginx_enabled | default(true)
|
||||
- role: postgresql
|
||||
when: database_enabled | default(true)
|
||||
- role: redis
|
||||
when: cache_enabled | default(false)
|
||||
```
|
||||
|
||||
### Условия на основе групп
|
||||
```yaml
|
||||
- name: Развертывание с групповыми условиями
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- role: nginx
|
||||
when: "'webservers' in group_names"
|
||||
- role: postgresql
|
||||
when: "'databases' in group_names"
|
||||
- role: monitoring
|
||||
when: "'monitoring' in group_names"
|
||||
```
|
||||
|
||||
## 7. Параллельное выполнение
|
||||
|
||||
### Настройка параллелизма
|
||||
```yaml
|
||||
- name: Развертывание с параллелизмом
|
||||
hosts: all
|
||||
become: true
|
||||
serial: 2 # Выполнять на 2 хостах одновременно
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
```
|
||||
|
||||
### Каскадное развертывание
|
||||
```yaml
|
||||
- name: Развертывание БД (первыми)
|
||||
hosts: databases
|
||||
become: true
|
||||
serial: 1
|
||||
roles:
|
||||
- postgresql
|
||||
|
||||
- name: Развертывание приложений (после БД)
|
||||
hosts: webservers
|
||||
become: true
|
||||
serial: 2
|
||||
roles:
|
||||
- nginx
|
||||
- application
|
||||
```
|
||||
|
||||
## 8. Обработка ошибок
|
||||
|
||||
### Игнорирование ошибок
|
||||
```yaml
|
||||
- name: Развертывание с игнорированием ошибок
|
||||
hosts: all
|
||||
become: true
|
||||
ignore_errors: true
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
```
|
||||
|
||||
### Обработка ошибок на уровне ролей
|
||||
```yaml
|
||||
- name: Развертывание с обработкой ошибок
|
||||
hosts: all
|
||||
become: true
|
||||
roles:
|
||||
- role: nginx
|
||||
ignore_errors: true
|
||||
- role: postgresql
|
||||
ignore_errors: false
|
||||
```
|
||||
|
||||
## 9. Инвентарь и подключение
|
||||
|
||||
### Различные пользователи
|
||||
```yaml
|
||||
- name: Развертывание с разными пользователями
|
||||
hosts: all
|
||||
become: true
|
||||
remote_user: "{{ ansible_user | default('ubuntu') }}"
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
```
|
||||
|
||||
### SSH настройки
|
||||
```yaml
|
||||
- name: Развертывание с SSH настройками
|
||||
hosts: all
|
||||
become: true
|
||||
gather_facts: true
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
vars:
|
||||
ansible_ssh_private_key_file: "~/.ssh/id_rsa"
|
||||
ansible_ssh_common_args: "-o StrictHostKeyChecking=no"
|
||||
```
|
||||
|
||||
## 10. Полный пример продакшн развертывания
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Полный пример продакшн развертывания
|
||||
# Автор: Сергей Антропов
|
||||
# Сайт: https://devops.org.ru
|
||||
|
||||
# 1. Развертывание инфраструктуры
|
||||
- name: Развертывание инфраструктуры
|
||||
hosts: infrastructure
|
||||
become: true
|
||||
serial: 1
|
||||
roles:
|
||||
- role: nginx
|
||||
vars:
|
||||
nginx_ssl_enabled: true
|
||||
nginx_ssl_cert: "{{ ssl_cert_path }}"
|
||||
nginx_ssl_key: "{{ ssl_key_path }}"
|
||||
tags: ['infrastructure', 'nginx']
|
||||
|
||||
# 2. Развертывание БД
|
||||
- name: Развертывание базы данных
|
||||
hosts: databases
|
||||
become: true
|
||||
serial: 1
|
||||
roles:
|
||||
- role: postgresql
|
||||
vars:
|
||||
postgresql_version: "13"
|
||||
postgresql_max_connections: 200
|
||||
postgresql_shared_buffers: "256MB"
|
||||
tags: ['database', 'postgresql']
|
||||
|
||||
# 3. Развертывание приложений
|
||||
- name: Развертывание приложений
|
||||
hosts: webservers
|
||||
become: true
|
||||
serial: 2
|
||||
roles:
|
||||
- role: nginx
|
||||
vars:
|
||||
nginx_upstream_servers: "{{ app_servers }}"
|
||||
tags: ['application', 'nginx']
|
||||
- role: application
|
||||
vars:
|
||||
app_version: "{{ app_version }}"
|
||||
app_environment: "{{ environment }}"
|
||||
tags: ['application']
|
||||
|
||||
# 4. Развертывание мониторинга
|
||||
- name: Развертывание мониторинга
|
||||
hosts: monitoring
|
||||
become: true
|
||||
when: monitoring_enabled | default(true)
|
||||
roles:
|
||||
- role: prometheus
|
||||
tags: ['monitoring', 'prometheus']
|
||||
- role: grafana
|
||||
tags: ['monitoring', 'grafana']
|
||||
```
|
||||
|
||||
## 11. Команды запуска
|
||||
|
||||
### Базовые команды
|
||||
```bash
|
||||
# Развертывание всех ролей
|
||||
make role deploy
|
||||
|
||||
# Развертывание с проверкой (dry-run)
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --check
|
||||
|
||||
# Развертывание с тегами
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --tags web,database
|
||||
|
||||
# Развертывание с переменными
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml -e "app_version=1.0.0"
|
||||
|
||||
# Развертывание с лимитом хостов
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --limit webservers
|
||||
```
|
||||
|
||||
### Продвинутые команды
|
||||
```bash
|
||||
# Развертывание с параллелизмом
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --forks 5
|
||||
|
||||
# Развертывание с детальным выводом
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml -vvv
|
||||
|
||||
# Развертывание с обработкой ошибок
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --force-handlers
|
||||
|
||||
# Развертывание с тестированием
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --check --diff
|
||||
```
|
||||
|
||||
## 12. Переменные окружения
|
||||
|
||||
### Использование переменных окружения
|
||||
```bash
|
||||
# Установка переменных окружения
|
||||
export ANSIBLE_HOST_KEY_CHECKING=False
|
||||
export ANSIBLE_SSH_RETRIES=3
|
||||
export ANSIBLE_TIMEOUT=30
|
||||
|
||||
# Развертывание
|
||||
make role deploy
|
||||
```
|
||||
|
||||
### Файл переменных
|
||||
```yaml
|
||||
# group_vars/all.yml
|
||||
ansible_user: ubuntu
|
||||
ansible_ssh_private_key_file: "~/.ssh/id_rsa"
|
||||
ansible_ssh_common_args: "-o StrictHostKeyChecking=no"
|
||||
|
||||
# Переменные приложения
|
||||
app_name: "my-application"
|
||||
app_version: "1.0.0"
|
||||
environment: "production"
|
||||
|
||||
# Переменные БД
|
||||
postgresql_version: "13"
|
||||
postgresql_max_connections: 200
|
||||
```
|
||||
|
||||
## 13. Безопасность
|
||||
|
||||
### Использование Vault
|
||||
```yaml
|
||||
# В deploy.yml
|
||||
- name: Развертывание с секретами
|
||||
hosts: all
|
||||
become: true
|
||||
vars:
|
||||
db_password: "{{ vault_db_password }}"
|
||||
ssl_cert: "{{ vault_ssl_cert }}"
|
||||
roles:
|
||||
- postgresql
|
||||
- nginx
|
||||
```
|
||||
|
||||
### Запуск с Vault
|
||||
```bash
|
||||
# Развертывание с паролем Vault
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --ask-vault-pass
|
||||
|
||||
# Развертывание с файлом пароля
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --vault-password-file .vault_pass
|
||||
```
|
||||
|
||||
## 14. Отладка и логирование
|
||||
|
||||
### Включение отладки
|
||||
```yaml
|
||||
- name: Развертывание с отладкой
|
||||
hosts: all
|
||||
become: true
|
||||
debug: true
|
||||
roles:
|
||||
- nginx
|
||||
- postgresql
|
||||
```
|
||||
|
||||
### Логирование
|
||||
```bash
|
||||
# Развертывание с логированием
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml --log-path /var/log/ansible.log
|
||||
|
||||
# Развертывание с детальным выводом
|
||||
ansible-playbook -i inventory/hosts.ini roles/deploy.yml -vvv
|
||||
```
|
||||
|
||||
## 15. Лучшие практики
|
||||
|
||||
### Структура файла
|
||||
1. **Комментарии** - описывайте каждый блок
|
||||
2. **Группировка** - логически группируйте роли
|
||||
3. **Переменные** - выносите переменные в отдельные файлы
|
||||
4. **Теги** - используйте теги для гибкости
|
||||
5. **Условия** - добавляйте условия для безопасности
|
||||
|
||||
### Рекомендации
|
||||
- Используйте `become: true` для системных ролей
|
||||
- Группируйте хосты по функциональности
|
||||
- Применяйте теги для модульности
|
||||
- Используйте переменные для конфигурации
|
||||
- Добавляйте условия для безопасности
|
||||
- Логируйте все операции
|
||||
- Тестируйте с `--check` перед развертыванием
|
||||
|
||||
## Заключение
|
||||
|
||||
Файл `roles/deploy.yml` - это центральный элемент развертывания. Правильная его настройка обеспечивает гибкость, безопасность и надежность развертывания Ansible ролей на продакшн серверах.
|
||||
|
||||
Для получения дополнительной информации см.:
|
||||
- [Создание ролей](creating-roles.md)
|
||||
- [Настройка CI/CD](cicd-setup.md)
|
||||
- [Мониторинг](monitoring.md)
|
||||
Reference in New Issue
Block a user