Интерфейс событий TrackDB между Saver, Tracker и Stager

Этот интерфейс не является прямым RPC между Saver и Stager. Компоненты обмениваются состоянием задачи через TrackDB и RabbitMQ:

  1. Saver пишет первичное событие BUILD/NEW в imageEvents.
  2. Materialized views TrackDB проецируют данные в stateEvents и imagesByNames.
  3. Tracker пишет RUNNING, DONE или FAIL в imageEvents по факту состояния Kubernetes Job.
  4. Tracker публикует completion-событие в RabbitMQ queue stager_queue.
  5. Stager читает stager_queue, проверяет данные в TrackDB, выбирает следующую стадию и пишет NEW для неё в imageEvents.

TrackDB tables

Источник событий:

imageEvents

Рабочая проекция статусов:

stateEvents

Проекция расширенных данных образа:

imagesByNames

stateEvents содержит компактную историю состояний:

ПолеТип/значенияОписание
insertTimeDateTime64(9)Время вставки события.
eventTimeDateTimeЛогическое время события.
eventStageBUILD, TEST, SIGN, PUSH, CLEANUPСтадия pipeline.
eventStageStateSUSPEND, NEW, REJECT, RUNNING, DONE, FAILСостояние стадии.
taskIdFixedString(26)ULID задачи.
userstringПользователь задачи.
stageImageNamestringИмя образа на текущей стадии.
stageImageTagstringТег образа на текущей стадии.
errorTypeNumuintКод ошибки.
errorMessagestringТекст ошибки.
registryNamestringRegistry.
imageIdstringID образа, если известен.

imagesByNames дополнительно хранит build context, Dockerfile path, Git URL исходников, опциональный Git URL Dockerfile, ветки, tags, architectures, entrypoints, annotations и userGID. Для gate-логики Stager использует entrypoints и userGID.

Событие Saver -> TrackDB

Saver вставляет в imageEvents событие BUILD/NEW. Значимые поля:

{
  "eventStage": "BUILD",
  "eventStageState": "NEW",
  "taskId": "01JBV2S4PGNV87EGC5WKYA0RND",
  "user": "alexander",
  "stageImageName": "project/image",
  "stageImageTag": "",
  "registryName": "registry.example.org",
  "buildGitURL": "https://github.com/user/repo.git",
  "buildGitBranch": "master",
  "gitDockerfileURL": "https://github.com/user/dockerfiles.git",
  "gitDockerfileBranch": "master",
  "buildConfigPath": "/path/to/config.yaml",
  "buildDockerfilePath": "images/app/Dockerfile",
  "buildContextPath": ".",
  "repoTags": ["latest", "1.0.0"],
  "architecture": ["amd64", "arm64"],
  "entrypoints": {
    "amd64": [["rpm", "--eval", "%_host_cpu"]],
    "all": [["nginx", "-v"]]
  },
  "annotations": {
    "org.opencontainers.image.source": "https://github.com/user/repo"
  },
  "userGID": 200
}

Событие Tracker -> Stager

Tracker дополняет контекст задачи из TrackDB и публикует в RabbitMQ queue stager_queue событие завершения или запуска стадии.

Минимально значимые поля:

{
  "taskid": "01JBV2S4PGNV87EGC5WKYA0RND",
  "eventStage": "BUILD",
  "eventStageState": "DONE",
  "user": "alexander",
  "stageImageName": "project/image",
  "stageImageTag": "",
  "registryName": "registry.example.org",
  "imageId": "",
  "errorTypeNum": 0,
  "errorMessage": ""
}

Stager обрабатывает только DONE и FAIL как управляющие состояния. NEW, RUNNING и SUSPEND подтверждаются, но не запускают следующую стадию.

Для стадии BUILD Stager берёт из imagesByNames следующие поля расположения сборки:

ПолеОбязательноеОписание
buildGitURLдаGit URL репозитория исходников и build context.
buildGitBranchнетВетка buildGitURL; пустое значение означает default branch.
gitDockerfileURLнетGit URL отдельного репозитория с Dockerfile; пустое значение означает, что Dockerfile находится в buildGitURL.
gitDockerfileBranchнетВетка gitDockerfileURL; имеет смысл только если gitDockerfileURL не пустой.
buildDockerfilePathдаПуть к Dockerfile относительно gitDockerfileURL, если он задан, иначе относительно buildGitURL.
buildContextPathнетПуть к build context внутри buildGitURL; не указывает на Dockerfile-репозиторий.

Логика Stager

Список стадий задаётся конфигурацией STAGES; допустимые значения:

BUILD, TEST, SIGN, PUSH, CLEANUP

Ограничения:

ПравилоОписание
Первая стадияДолжна быть BUILD.
Последняя стадияДолжна быть CLEANUP.
Обязательная стадияPUSH должна присутствовать.
ПорядокBUILD < PUSH < CLEANUP.
TEST gateСтадия запускается только если в задаче есть непустой map entrypoints. Ключи map — нормализованные архитектуры или all.
SIGN gateСтадия запускается только если userGID совпадает с SIGN_USER_GID.
FAILЛюбой FAIL до CLEANUP маршрутизируется в CLEANUP, если она есть в STAGES.

При выборе следующей стадии Stager:

  1. Проверяет, что для taskId + eventStage ещё нет последнего NEW.
  2. Пишет новое событие в imageEvents.
  3. Публикует stage-event в очередь Distributor.

Формат stage-event описан в интерфейсе Stager/Distributor.