Add ansible/webserver-automation/ansible.md

2026-01-06 14:51:21 +00:00
parent e3db55a17c
commit c6f239839c
1 changed files with 781 additions and 0 deletions
--- a/ansible/webserver-automation/ansible.md
+++ b/ansible/webserver-automation/ansible.md
@@ -0,0 +1,781 @@
 # 📘 Ansible Web Server Automation - Полная Инструкция
 ## 🎯 Содержание
 1. [Требования](#требования)
 2. [Установка Ansible](#установка-ansible)
 3. [Настройка SSH](#настройка-ssh)
 4. [Клонирование проекта](#клонирование-проекта)
 5. [Настройка inventory](#настройка-inventory)
 6. [Настройка переменных](#настройка-переменных)
 7. [Тестирование подключения](#тестирование-подключения)
 8. [Запуск playbook](#запуск-playbook)
 9. [Проверка результата](#проверка-результата)
 10. [Деплой приложения](#деплой-приложения)
 11. [Troubleshooting](#troubleshooting)
 ---
 ## 1. Требования
 ### Управляющая машина (ваш компьютер)
 - Ubuntu 20.04+ / Debian 11+ / macOS / Windows WSL2
 - Python 3.6+
 - Git
 - SSH client
 ### Целевые серверы
 - Ubuntu 20.04 / 22.04 (рекомендуется)
 - Debian 10 / 11
 - Минимум 1GB RAM, 10GB диск
 - SSH доступ
 - Sudo права
 ---
 ## 2. Установка Ansible
 ### Ubuntu / Debian
 ```bash
 # Обновить систему
 sudo apt update
 sudo apt upgrade -y
 # Установить зависимости
 sudo apt install -y software-properties-common
 # Добавить PPA репозиторий Ansible (опционально, для последней версии)
 sudo add-apt-repository --yes --update ppa:ansible/ansible
 # Установить Ansible
 sudo apt install -y ansible
 # Проверить установку
 ansible --version
 ```
 Должно показать:
 ```
 ansible [core 2.14.x]
  python version = 3.x.x
  jinja version = 3.x.x
 ```
 ### macOS
 ```bash
 # Установить Homebrew (если нет)
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 # Установить Ansible
 brew install ansible
 # Проверить
 ansible --version
 ```
 ### Windows WSL2
 ```bash
 # Открыть Ubuntu в WSL2
 wsl
 # Следовать инструкциям для Ubuntu выше
 sudo apt update
 sudo apt install -y ansible
 ```
 ---
 ## 3. Настройка SSH
 ### 3.1 Генерация SSH ключа
 На управляющей машине:
 ```bash
 # Генерировать SSH ключ (если нет)
 ssh-keygen -t ed25519 -C "your_email@example.com"
 # Или RSA (более совместимый)
 ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
 # Нажать Enter для defaults
 # Ключи сохранятся в ~/.ssh/id_ed25519 (или id_rsa)
 ```
 ### 3.2 Копирование ключа на сервер
 ```bash
 # Скопировать ключ на целевой сервер
 ssh-copy-id ubuntu@192.168.1.10
 # Или вручную
 cat ~/.ssh/id_ed25519.pub | ssh ubuntu@192.168.1.10 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
 ```
 ### 3.3 Тест SSH подключения
 ```bash
 # Подключиться без пароля
 ssh ubuntu@192.168.1.10
 # Если успешно - можно продолжать!
 exit
 ```
 ---
 ## 4. Клонирование проекта
 ```bash
 # Клонировать репозиторий
 git clone http://git.thedevops.dev/admin/k3s-gitops.git
 # Перейти в директорию проекта
 cd k3s-gitops/ansible/webserver-automation
 # Проверить структуру
 tree
 ```
 Должна быть структура:
 ```
 ansible/webserver-automation/
 ├── README.md
 ├── ansible.cfg
 ├── inventory/
 │   └── production
 ├── group_vars/
 │   ├── all.yml
 │   └── webservers.yml
 ├── playbooks/
 │   ├── site.yml
 │   └── deploy.yml
 └── roles/
    ├── common/
    ├── nginx/
    └── firewall/
 ```
 ---
 ## 5. Настройка Inventory
 ### 5.1 Редактировать production inventory
 ```bash
 # Открыть файл
 vim inventory/production
 ```
 ### 5.2 Заменить на свои данные
 ```ini
 # Production Inventory
 # Замените IP адреса на свои!
 [webservers]
 web1.example.com ansible_host=192.168.1.10
 web2.example.com ansible_host=192.168.1.11
 [all:vars]
 ansible_user=ubuntu                           # Ваш SSH пользователь
 ansible_ssh_private_key_file=~/.ssh/id_rsa  # Путь к SSH ключу
 ansible_python_interpreter=/usr/bin/python3
 environment=production
 ```
 ### 5.3 Простой пример (один сервер)
 ```ini
 [webservers]
 web1 ansible_host=192.168.1.10
 [all:vars]
 ansible_user=ubuntu
 ansible_ssh_private_key_file=~/.ssh/id_ed25519
 environment=production
 ```
 ### 5.4 Для Vagrant / локального тестирования
 ```ini
 [webservers]
 localhost ansible_connection=local
 [all:vars]
 ansible_user=vagrant
 environment=development
 ```
 ---
 ## 6. Настройка переменных
 ### 6.1 Общие переменные
 ```bash
 # Открыть файл
 vim group_vars/all.yml
 ```
 Настройте базовые параметры:
 ```yaml
 ---
 # Система
 timezone: "Europe/Vilnius"  # Ваш timezone
 # Пользователи
 admin_users:
  - name: admin
    groups: sudo
    shell: /bin/bash
  - name: deploy
    groups: www-data
    shell: /bin/bash
 # Пакеты
 common_packages:
  - curl
  - wget
  - git
  - vim
  - htop
  - ufw
 # SSH
 ssh_port: 22
 ssh_password_authentication: false
 # Firewall
 firewall_allowed_tcp_ports:
  - 22   # SSH
  - 80   # HTTP
  - 443  # HTTPS
 ```
 ### 6.2 Переменные веб-сервера
 ```bash
 # Открыть файл
 vim group_vars/webservers.yml
 ```
 Настройте параметры приложения:
 ```yaml
 ---
 # Nginx
 nginx_port: 80
 nginx_ssl_port: 443
 # Приложение
 app_name: "myapp"           # Имя вашего приложения
 app_user: "webapp"
 app_group: "www-data"
 app_dir: "/var/www/{{ app_name }}"
 # Домен
 domain_name: "example.com"  # Ваш домен
 server_name: "{{ inventory_hostname }}"
 # SSL (отключить если нет сертификата)
 ssl_enabled: false
 # Логи
 access_log: "/var/log/nginx/{{ app_name }}_access.log"
 error_log: "/var/log/nginx/{{ app_name }}_error.log"
 # Performance
 client_max_body_size: "100M"
 gzip_enabled: true
 ```
 ---
 ## 7. Тестирование подключения
 ### 7.1 Проверить синтаксис inventory
 ```bash
 ansible-inventory -i inventory/production --list
 ```
 ### 7.2 Ping тест
 ```bash
 # Проверить подключение ко всем хостам
 ansible -i inventory/production all -m ping
 # Ожидаемый результат:
 # web1 | SUCCESS => {
 #     "changed": false,
 #     "ping": "pong"
 # }
 ```
 ### 7.3 Проверить доступ sudo
 ```bash
 ansible -i inventory/production all -m shell -a "whoami" --become
 ```
 Должно показать: `root`
 ### 7.4 Собрать факты о системе
 ```bash
 ansible -i inventory/production all -m setup
 ```
 ---
 ## 8. Запуск Playbook
 ### 8.1 Синтаксис проверка
 ```bash
 # Проверить синтаксис playbook
 ansible-playbook -i inventory/production playbooks/site.yml --syntax-check
 # Должно показать:
 # playbook: playbooks/site.yml
 ```
 ### 8.2 Dry Run (тест без изменений)
 ```bash
 # Запустить в режиме проверки
 ansible-playbook -i inventory/production playbooks/site.yml --check
 # Покажет что будет изменено, но не применит изменения
 ```
 ### 8.3 Список задач
 ```bash
 # Посмотреть все задачи
 ansible-playbook -i inventory/production playbooks/site.yml --list-tasks
 ```
 ### 8.4 Полный запуск
 ```bash
 # Запустить полную установку
 ansible-playbook -i inventory/production playbooks/site.yml
 # С verbose output (для отладки)
 ansible-playbook -i inventory/production playbooks/site.yml -v
 # Очень подробный вывод
 ansible-playbook -i inventory/production playbooks/site.yml -vvv
 ```
 ### 8.5 Ход выполнения
 Вы увидите примерно такой вывод:
 ```
 PLAY [Setup all servers] *********************************************
 TASK [Gathering Facts] ***********************************************
 ok: [web1]
 TASK [Display deployment information] ********************************
 ok: [web1] => {
    "msg": "Deploying to: web1\nEnvironment: production\n..."
 }
 PLAY [Configure common settings] *************************************
 TASK [common : Update apt cache] *************************************
 changed: [web1]
 TASK [common : Install common packages] ******************************
 changed: [web1]
 ...
 PLAY RECAP ***********************************************************
 web1                       : ok=25   changed=15   unreachable=0    failed=0
 ```
 ### 8.6 Запуск конкретных тегов
 ```bash
 # Только обновить пакеты
 ansible-playbook -i inventory/production playbooks/site.yml --tags packages
 # Только настроить firewall
 ansible-playbook -i inventory/production playbooks/site.yml --tags firewall
 # Только nginx
 ansible-playbook -i inventory/production playbooks/site.yml --tags nginx
 # Несколько тегов
 ansible-playbook -i inventory/production playbooks/site.yml --tags "packages,nginx"
 ```
 ### 8.7 Ограничить выполнение на один хост
 ```bash
 # Только для web1
 ansible-playbook -i inventory/production playbooks/site.yml --limit web1
 # Для нескольких хостов
 ansible-playbook -i inventory/production playbooks/site.yml --limit "web1,web2"
 ```
 ---
 ## 9. Проверка результата
 ### 9.1 Проверить веб-сервер
 ```bash
 # С управляющей машины
 curl http://192.168.1.10
 # Должен вернуть HTML страницу
 ```
 ### 9.2 Проверить в браузере
 Открыть в браузере:
 ```
 http://192.168.1.10
 ```
 Вы должны увидеть красивую страницу с:
 - 🚀 emoji
 - Название приложения
 - Environment: production
 - Server: web1
 - "Deployed with Ansible ✨"
 ### 9.3 Проверить health endpoint
 ```bash
 curl http://192.168.1.10/health
 # Должен вернуть: healthy
 ```
 ### 9.4 Проверить Nginx статус
 ```bash
 # На сервере
 ssh ubuntu@192.168.1.10
 sudo systemctl status nginx
 # Должно показать: active (running)
 ```
 ### 9.5 Проверить firewall
 ```bash
 # На сервере
 ssh ubuntu@192.168.1.10
 sudo ufw status
 # Должно показать:
 # Status: active
 # To                         Action      From
 # --                         ------      ----
 # 22/tcp                     ALLOW       Anywhere
 # 80/tcp                     ALLOW       Anywhere
 # 443/tcp                    ALLOW       Anywhere
 ```
 ### 9.6 Проверить логи
 ```bash
 # На сервере
 ssh ubuntu@192.168.1.10
 # Access logs
 sudo tail -f /var/log/nginx/myapp_access.log
 # Error logs
 sudo tail -f /var/log/nginx/myapp_error.log
 ```
 ---
 ## 10. Деплой приложения
 ### 10.1 Базовый деплой
 ```bash
 # Задеплоить приложение
 ansible-playbook -i inventory/production playbooks/deploy.yml
 ```
 ### 10.2 Деплой с версией
 ```bash
 # Указать версию
 ansible-playbook -i inventory/production playbooks/deploy.yml -e "app_version=v1.2.3"
 ```
 ### 10.3 Что делает deploy playbook
 1. ✅ Создаёт директорию приложения
 2. ✅ Деплоит HTML файл
 3. ✅ Перезапускает Nginx
 4. ✅ Проверяет доступность
 ### 10.4 Кастомизация HTML
 Отредактируйте в playbook `playbooks/deploy.yml`:
 ```yaml
 - name: Deploy custom HTML
  copy:
    dest: "{{ app_dir }}/index.html"
    content: |
      <!DOCTYPE html>
      <html>
      <head>
          <title>My Custom App</title>
      </head>
      <body>
          <h1>Welcome to My App!</h1>
          <p>Version: {{ app_version }}</p>
      </body>
      </html>
 ```
 ---
 ## 11. Troubleshooting
 ### Проблема 1: SSH connection failed
 **Ошибка:**
 ```
 fatal: [web1]: UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host"}
 ```
 **Решение:**
 ```bash
 # Проверить SSH подключение вручную
 ssh ubuntu@192.168.1.10
 # Проверить SSH ключ
 ssh-add -l
 # Добавить ключ если нужно
 ssh-add ~/.ssh/id_rsa
 # Проверить права на ключ
 chmod 600 ~/.ssh/id_rsa
 ```
 ### Проблема 2: Permission denied (sudo)
 **Ошибка:**
 ```
 fatal: [web1]: FAILED! => {"msg": "Missing sudo password"}
 ```
 **Решение:**
 ```bash
 # Запустить с запросом sudo пароля
 ansible-playbook -i inventory/production playbooks/site.yml --ask-become-pass
 # Или добавить пользователя в sudoers без пароля
 ssh ubuntu@192.168.1.10
 sudo visudo
 # Добавить строку:
 ubuntu ALL=(ALL) NOPASSWD:ALL
 ```
 ### Проблема 3: Module not found
 **Ошибка:**
 ```
 ERROR! couldn't resolve module/action 'community.general.ufw'
 ```
 **Решение:**
 ```bash
 # Установить Ansible collections
 ansible-galaxy collection install community.general
 ansible-galaxy collection install ansible.posix
 ```
 ### Проблема 4: Port 80 already in use
 **Ошибка:**
 ```
 nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)
 ```
 **Решение:**
 ```bash
 # Найти процесс на порту 80
 ssh ubuntu@192.168.1.10
 sudo lsof -i :80
 # Остановить Apache если запущен
 sudo systemctl stop apache2
 sudo systemctl disable apache2
 # Перезапустить Nginx
 sudo systemctl restart nginx
 ```
 ### Проблема 5: Syntax error in playbook
 **Ошибка:**
 ```
 ERROR! We were unable to read either as JSON nor YAML
 ```
 **Решение:**
 ```bash
 # Проверить YAML синтаксис
 yamllint playbooks/site.yml
 # Или онлайн: http://www.yamllint.com/
 # Проверить отступы (должны быть пробелы, не табы!)
 ```
 ### Проблема 6: Firewall блокирует HTTP
 **Ошибка:**
 ```
 curl: (7) Failed to connect to 192.168.1.10 port 80: Connection refused
 ```
 **Решение:**
 ```bash
 # Проверить UFW
 ssh ubuntu@192.168.1.10
 sudo ufw status
 # Добавить правило если нужно
 sudo ufw allow 80/tcp
 sudo ufw reload
 ```
 ### Проблема 7: Slow playbook execution
 **Решение:**
 ```bash
 # Включить pipelining в ansible.cfg
 echo "pipelining = True" >> ansible.cfg
 # Отключить gathering facts если не нужны
 ansible-playbook playbooks/site.yml --skip-tags=facts
 # Использовать Strategy plugin
 # В playbook добавить:
 strategy: free
 ```
 ---
 ## 📚 Дополнительные команды
 ### Полезные ad-hoc команды
 ```bash
 # Перезапустить Nginx на всех серверах
 ansible -i inventory/production webservers -m service -a "name=nginx state=restarted" --become
 # Проверить uptime
 ansible -i inventory/production all -m shell -a "uptime"
 # Проверить disk space
 ansible -i inventory/production all -m shell -a "df -h"
 # Обновить пакеты
 ansible -i inventory/production all -m apt -a "update_cache=yes upgrade=dist" --become
 # Скопировать файл на все серверы
 ansible -i inventory/production webservers -m copy -a "src=./file.txt dest=/tmp/file.txt"
 # Получить информацию о процессе
 ansible -i inventory/production webservers -m shell -a "ps aux | grep nginx"
 ```
 ### Ansible Vault (для секретов)
 ```bash
 # Создать зашифрованный файл
 ansible-vault create group_vars/production_secrets.yml
 # Редактировать
 ansible-vault edit group_vars/production_secrets.yml
 # Запустить playbook с vault
 ansible-playbook -i inventory/production playbooks/site.yml --ask-vault-pass
 # Или с файлом пароля
 echo "mypassword" > .vault_pass
 ansible-playbook -i inventory/production playbooks/site.yml --vault-password-file .vault_pass
 ```
 ---
 ## 🎓 Следующие шаги
 ### 1. Добавить мониторинг
 - Prometheus
 - Grafana
 - Node Exporter
 ### 2. Добавить SSL сертификаты
 - Let's Encrypt
 - Certbot automation
 ### 3. Добавить CI/CD
 - Интеграция с Jenkins
 - GitLab CI
 - GitHub Actions
 ### 4. Масштабирование
 - Добавить Load Balancer
 - Настроить Database servers
 - Redis/Memcached
 ---
 ## 📞 Поддержка
 - **Документация:** http://git.thedevops.dev/admin/k3s-gitops/src/branch/main/ansible/webserver-automation
 - **Issues:** http://git.thedevops.dev/admin/k3s-gitops/issues
 - **Ansible Docs:** https://docs.ansible.com
 ---
 ## ✅ Checklist успешной установки
 - [ ] Ansible установлен (`ansible --version`)
 - [ ] SSH ключи настроены
 - [ ] Проект склонирован
 - [ ] Inventory настроен с реальными IP
 - [ ] Variables настроены (timezone, domain, etc)
 - [ ] SSH ping успешен (`ansible all -m ping`)
 - [ ] Playbook запущен (`ansible-playbook playbooks/site.yml`)
 - [ ] Сайт доступен (`curl http://SERVER_IP`)
 - [ ] Firewall работает (`sudo ufw status`)
 - [ ] Nginx работает (`systemctl status nginx`)
 - [ ] Deploy работает (`ansible-playbook playbooks/deploy.yml`)
 ---
 **Версия:** 1.0.0  
 **Дата:** 2026-01-06  
 **Статус:** ✅ Production Ready