DevOpsLab/docs/deploy-yml-customization.md

# Кастомизация 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)