Обзор архитектуры проекта

Введение

Данный документ описывает архитектуру проекта автоматизированного конвейера сборки OCI-образов. Система принимает запросы на сборку, раскладывает их на последовательность стадий, запускает Kubernetes Job для каждой стадии и сохраняет состояние выполнения в TrackDB.

Архитектура построена вокруг асинхронного обмена событиями через RabbitMQ. Компоненты не вызывают друг друга напрямую для продвижения задания по конвейеру: они публикуют события стадий, а состояние задания фиксируется в TrackDB.

Схема архитектуры

архитектурная схема, загрузка

Основные компоненты

1. API

Описание: API служит внешним интерфейсом конвейера. Он принимает запросы на сборку, возвращает статус задания и логи, выполняет аутентификацию и авторизацию пользователей. Для каждого запроса на сборку OCI-образа формируется уникальный taskId.

Функции:

  • Выполняет keycloak-аутентификацию пользователей, создаёт и проверяет записи пользователей в таблицах SysDB.
  • Выпускает токен для авторизации пользователей.
  • Выполняет авторизацию пользователей, проверяя токен и сверяясь с таблицами SysDB.
  • Обрабатывает запросы на сборку, присваивая ULID в виде taskId.
  • Отправляет запросы на сборку в RabbitMQ для последующей обработки компонентом Saver.
  • Получает статусы сборки из TrackDB.
  • Получает логи из Loki через observability-контур.

2. API-LITE

Описание: упрощённая версия API без подключения к Keycloak. Она предназначена для сценариев, где используется один заранее настроенный пользователь и статический токен авторизации.

3. Компонент Saver

Описание: Saver принимает запросы от API из RabbitMQ, валидирует данные запроса, записывает стартовое состояние задания в TrackDB, сохраняет пользовательские credentials в Secret Manager и отправляет первую стадию BUILD в Distributor.

Функции:

  • Извлекает запросы на сборку из очереди RabbitMQ.
  • Создаёт первую запись о задании в TrackDB со стадией BUILD и состоянием NEW.
  • Записывает credentials пользователя для доступа к git и registry в Secret Manager.
  • Отправляет событие BUILD/NEW через RabbitMQ в компонент Distributor.

4. Компонент Stager

Описание: Stager получает от Tracker события завершения стадий и определяет следующую стадию конвейера. Список стадий задаётся конфигурацией и обычно включает BUILD, опциональные TEST и SIGN, затем PUSH и CLEANUP.

Функции:

  • Подписан на события RabbitMQ от Tracker.
  • Обрабатывает состояния DONE и FAIL.
  • При DONE выбирает следующую стадию с учётом настроек задания: TEST выполняется только при наличии test entrypoints, SIGN выполняется только для настроенных групп пользователей.
  • При FAIL отправляет задание на CLEANUP, если эта стадия включена в конфигурацию.
  • Записывает NEW для следующей стадии в TrackDB и отправляет её в Distributor.

5. Компонент Distributor

Описание: Distributor получает события стадий из RabbitMQ и разворачивает соответствующий Helm chart в Kubernetes. Для каждой стадии создаётся отдельный Helm release с именем, основанным на taskId и названии стадии.

Функции:

  • Извлекает события стадий из очереди RabbitMQ.
  • Получает параметры Helm chart для стадии из SysDB.
  • Подставляет параметры задания в values chart'а.
  • Для стадий, которым нужны credentials, получает их из Secret Manager.
  • Выполняет helm upgrade --install для запуска Kubernetes Job в namespace altflow.
  • После успешного запуска Job записывает состояние SUSPEND в TrackDB. Это состояние трактуется как "задание поставлено в Kubernetes и ожидает выполнения".

6. Компонент Tracker

Описание: Tracker отслеживает Kubernetes pod'ы, созданные стадийными Job'ами, и переводит состояние стадии в TrackDB. Для распределения ответственности между несколькими экземплярами Tracker используется hash ring по taskId.

Функции:

  • Отслеживает pod'ы стадий через Kubernetes LIST/WATCH.
  • Пишет RUNNING, когда рабочий контейнер стадии начал выполняться.
  • Пишет DONE или FAIL после завершения рабочего контейнера.
  • Отправляет финальные состояния стадий через RabbitMQ в Stager.
  • Выполняет периодическую сверку с TrackDB и помечает orphan-задачи как FAIL, если в TrackDB стадия числится RUNNING, но соответствующего pod'а больше нет.
  • Удаляет Helm release стадии после обработки финального состояния.

7. Компонент Builder

Описание: Builder обеспечивает выполнение стадий сборки и тестирования OCI-образов в Kubernetes.

Функции:

  • Подготавливает ноды Kubernetes для мультиархитектурной сборки через binfmt/qemu.
  • Предоставляет runtime-образ для Job'ов стадий BUILD и TEST.
  • Используется Helm job packages для запуска стадий BUILD, TEST, SIGN, PUSH и CLEANUP.

8. Observability

Описание: Observability-контур собирает метрики и логи компонентов системы и стадийных Job'ов.

Функции:

  • Vector собирает логи pod'ов и отправляет их в Loki.
  • Loki хранит логи стадий и отдаёт их API для пользовательских запросов.
  • Prometheus собирает метрики компонентов и Kubernetes-объектов.
  • kube-state-metrics отдаёт Prometheus состояние Kubernetes-ресурсов.
  • HAProxy публикует защищённые endpoint'ы для доступа к Loki и Prometheus.
  • Grafana может быть развёрнута опционально как пользовательский интерфейс для метрик и логов.

9. SysDB, Secret Manager и TrackDB

Описание:

  • SysDB: Хранит конфигурационные данные и специальные параметры для запросов на сборку, установленные администратором. Хранит информацию о пользователях для их авторизации.
  • Secret Manager: Хранит пользовательские credentials по каждому taskId, а также чувствительную информацию, необходимую для развёртывания и работы компонентов altflow.
  • TrackDB: ClickHouse-хранилище событий стадий. Содержит историю состояний заданий и обеспечивает доступ к этой информации для API, Stager, Tracker и Distributor.

Эти компоненты работают совместно, обеспечивая эффективный и автоматизированный процесс сборки OCI-образов в рамках конвейера.

Развертывание

Архитектура проекта предназначена для развёртывания в Kubernetes. Кластерные компоненты поставляются как Helm charts и Flux HelmRelease-манифесты. Стадийные Job'ы также запускаются через Helm charts, которые Distributor устанавливает для конкретного taskId и стадии.

Преимущества и недостатки

Преимущества

  • Масштабируемость: Компоненты обмениваются событиями через RabbitMQ, а независимые стадии выполняются отдельными Kubernetes Job'ами.
  • Микросервисная архитектура: Компоненты реализуют простые операции, что упрощает разработку и позволяет использовать различные языки программирования при соблюдении единого интерфейса взаимодействия.
  • Наблюдаемость: Логи и метрики собираются отдельным observability-контуром.

Недостатки

  • Сложность архитектуры: Для работы системы нужны Kubernetes, RabbitMQ, SysDB, TrackDB, Secret Manager и observability-контур.
  • Высокий порог входа для администрирования и отладки распределённых сценариев.

Заключение

Архитектура проекта автоматизированного конвейера сборки OCI-образов разработана с акцентом на масштабируемость и разделение ответственности. API принимает пользовательские запросы, Saver фиксирует старт задания, Distributor запускает стадии в Kubernetes, Tracker завершает стадии по фактическому состоянию pod'ов, а Stager продвигает задание по конвейеру.