Введение: Важно понимать общую картину

Здравствуйте! В первой части мы обсудили причины создания системы автоматического развертывания с использованием GitHub Webhook и необходимые подготовительные шаги. Во второй части мы уделим время проектированию общей архитектуры и процессов нашей автоматической системы развертывания перед началом реализации кода.

Каждая среда разработки может немного отличаться. Некоторые могут использовать Raspberry Pi, другие - облачный VPS, а структура проекта, который нужно развернуть, будет различной. Для того чтобы гибко построить систему в таких различных условиях и самостоятельно решать возникающие проблемы, важно понимать общие потоки и контекст, а не только детали кода.

В этой части постараемся представить общую картину системы, которую мы создаем, и четко понять, какую роль играют каждый из ее компонентов.

Схема автоматического развертывания

Рабочий процесс автоматического развертывания: Обзор общего потока

Наша реализуемая система автоматического развертывания будет работать по следующему процессу.

  1. Изменение кода на локальной машине и Git push: Разработчик вносит изменения в код в локальной среде и отправляет изменения в конкретную ветку GitHub репозитория (например, main или develop).

  2. Происхождение события webhook в репозитории GitHub: Когда в репозитории GitHub обнаруживается событие push, он отправляет HTTP POST запрос на указанный URL через ранее настроенный webhook.

  3. Передача запроса на конечную точку webhook на staging-сервере: Запрос webhook от GitHub будет направлен на определенный URL нашего staging-сервера (например, https://deployer.example.com/webhook). Этот запрос включает в себя разнообразные полезные данные (Payload), такие как информация о коммите и список измененных файлов.

  4. Получение webhook запросов сервисом FastAPI на staging-сервере: Наша FastAPI-приложение, работающее на staging-сервере, получает этот запрос webhook. С этого момента начинается роль сервиса FastAPI.

Ключевая роль сервиса FastAPI Webhook

Сервис webhook, реализованный на FastAPI, будет выполнять не только прием запросов, но и важные функции, такие как:

Прием и первоначальная обработка webhook

Приложение FastAPI предоставляет конечную точку (например, /webhook), которая может принимать HTTP POST запросы от GitHub. Эта конечная точка парсит HTTP-заголовки и тело запроса (Payload), извлекая необходимую информацию.

Проверка Secret

Безопасность является самым важным аспектом системы автоматического развертывания. GitHub Webhook предоставляет значение Secret через заголовок X-Hub-Signature-256 для проверки целостности запроса. Наш сервис FastAPI должен включать логику, использующую это значение Secret, для проверки, идет ли запрос от GitHub и не был ли он изменен во время передачи. Если проверка не пройдет, запрос будет немедленно отклонен, что будет препятствовать несанкционированному доступу.

Немедленный ответ и фоновые задачи

Если GitHub не получит ответ в течение определенного времени (по умолчанию 10 секунд) после отправки запроса, он будет считать это тайм-аутом и попытается повторить или зафиксировать ошибку. Однако сама процедура развертывания (Git Pull, сборка Docker/перезапуск и т.д.) может занять больше времени.

Поэтому наш сервис FastAPI немедленно отправит ответ 200 OK в GitHub после завершения первоначальной обработки, такой как проверка Secret, и фактическая логика развертывания будет запущена в фоновом режиме, используя функционал BackgroundTasks от FastAPI, что позволит выполнять асинхронные задачи в фоновом режиме. Это поможет избежать проблем с тайм-аутами со стороны GitHub, сохраняя стабильность выполнения задач развертывания.

Детали логики обработчика развертывания

Фоновый обработчик, который будет выполняться, выполняет несколько ключевых задач.

Управление несколькими проектами: чтение путей репозиториев

Мы спроектируем один сервис FastAPI webhook, который сможет обрабатывать автоматические развертывания для нескольких репозиториев GitHub (проектов). Для этого мы будем управлять путем репозитория GitHub каждого проекта и локальным путем на сервере, где будет проходить развертывание, через переменные окружения или файлы настроек. Выявив, в каком репозитории произошло событие с помощью полезной нагрузки вебхука, мы перейдем к соответствующему пути проекта для выполнения работы по развертыванию.

Индивидуальные настройки для проектов: Парсинг файла .env (по желанию)

Каждый проект может иметь свои уникальные переменные окружения или настройки, необходимые для сборки или развертывания. Например, определенные теги образа Docker, параметры сборки или команды перезапуска сервиса могут различаться. Чтобы эффективно управлять этими настройками, мы реализуем парсинг необходимых значений из файла .env, находящегося в локальном пути хранилища каждого проекта, для использования в логике развертывания. Это будет полезно для реализации гибкой и настраиваемой логики развертывания.

Обновление кода: выполнение git pull

Это самый базовый этап. Используя модуль subprocess, мы выполняем команду git pull origin <branch_name> в локальном хранилище соответствующего проекта для получения актуального кода из репозитория GitHub.

Решение о пересборке образа Docker: использование git diff

Для проектов на основе Docker, когда изменяется только код, достаточно выполнить docker compose up -d, но если изменены файлы, влияющие на сборку образа Docker, такие как Dockerfile или requirements.txt (для проектов на Python), образ необходимо пересобрать.

Мы будем использовать команду git diff для определения изменений между последним коммитом и предыдущим, чтобы установить, изменились ли Dockerfile или другие файлы, связанные со сборкой. Если изменения будут обнаружены, будет выполнена команда docker compose up -d --build, в противном случае будет выполнена просто docker compose up -d, чтобы избежать ненужной пересборки образа и сократить время развертывания.

Выполнение Docker Compose: использование модуля subprocess

После того, как мы извлечем актуальный код и установим, необходимо ли пересобирать образ, мы используем модуль subprocess для выполнения команд docker compose up -d или docker compose up -d --build, чтобы обновить контейнер Docker до последнего состояния и перезапустить сервис.

Логирование: запись всех процессов

Все процессы развертывания (прием вебхука, проверка, результаты Git Pull, логи сборки/перезапуска Docker и т.д.) должны подробно документироваться. Это необходимо для диагностики причин в случае возникновения проблем. Мы реализуем запись логов в файл с помощью модуля logging Python.

Стратегия развертывания и эксплуатации сервиса FastAPI

Создаваемый нами сервис FastAPI webhook должен быть стабильным и всегда быть запущен на staging-сервере.

Важность использования Systemd Service

Мы настоятельно рекомендуем запускать приложение FastAPI как Systemd Service, а не напрямую в контейнере Docker. Причины следующи:

  • Эффективность ресурсов: На staging-сервере с высокой вероятностью уже установлены необходимые инструменты для развертывания, такие как git, docker, docker compose. Создание сервиса FastAPI как контейнера Docker, а затем установка git или docker внутри этого контейнера для управления демоном docker будут необоснованными и увеличат размер контейнера, а также могут вызвать сложные настройки и проблемы безопасности, такие как docker-in-docker или docker-out-of-docker.

  • Упрощенное управление: Systemd является стандартом управления сервисами в системах Linux. Регистрация приложения FastAPI как Systemd сервиса предоставляет возможность автоматического старта при загрузке сервера, проверки состояния сервиса, простого перезапуска и остановки, и дает интегрированное и упрощенное управление на уровне ОС.

  • Использование ресурсов системы: Запуская приложение FastAPI через Systemd, оно может напрямую вызывать установленные в системе команды git и docker для выполнения развертывания, эффективно используя существующие ресурсы системы.

В следующей части мы подробно объясним, как зарегистрировать и управлять приложением FastAPI как службой Systemd.

Обратный прокси и HTTPS через Nginx/Apache2

Как мы подчеркивали в первой части, прямое размещение приложения FastAPI в интернете очень рискованно с точки зрения безопасности. Поэтому мы будем использовать веб-сервер, такой как Nginx или Apache2, в качестве обратного прокси (Reverse Proxy), чтобы безопасно передавать запросы вебхука в приложение FastAPI.

Кроме того, GitHub Webhook настоятельно рекомендует использовать HTTPS, поэтому необходимо подготовить выделенный сабдомен, такой как deployer.example.com, и получить HTTPS сертификат через Let's Encrypt и применить его к веб-серверу. Это обеспечит шифрование всех внешних коммуникаций и усилит безопасность.

Мониторинг и отладка

Для проверки правильности работы автоматической системы развертывания и выявления причин возникающих проблем мы будем использовать два метода.

  • Лог-файлы сервиса FastAPI: Разрабатываемый нами сервис FastAPI будет записывать все этапы процесса развертывания в собственный лог-файл. Проверяя этот файл, можно будет установить успешность развертывания и выявить возникшие сообщения об ошибках.

  • Systemd journalctl: Поскольку мы управляем сервисом FastAPI через Systemd, можно будет использовать команду journalctl -u your-fastapi-service.service для одновременной проверки и анализа стандартного вывода и логов ошибок сервиса в реальном времени.

В заключение: Предстоящая часть

Во второй части мы подробно рассмотрели общую архитектуру автоматически развертываемой системы с использованием GitHub Webhook, ключевую роль сервиса FastAPI и стратегии развертывания и эксплуатации. Теперь у вас, надеюсь, сложилась общая картина в голове.

В следующей третьей части мы, основываясь на разработанном сегодня дизайне, напишем код для реального сервиса FastAPI webhook, установим GitHub Webhook и зарегистрируем его как службу Systemd. Ожидайте!

Серия по созданию собственной системы автоматического развертывания с использованием GitHub Webhook

Часть 1 - Почему мы реализуем это самостоятельно?