Формат спецификаций в org

В директории образа в обязательном порядке должны находится следующие файлы:

  • Dockerfile.template
  • info.yaml
  • altflow-test

Файлы, подобные Dockerfile.sisyphus и info.sisyphus.yaml, являются автоматически сгенерированными артефактами и не должны попадать в основную ветку репозитория.

Рабочие ветки и *-artefacts

Рабочая ветка содержит только исходную спецификацию образа:

  • Dockerfile.template
  • info.yaml
  • altflow-test
  • дополнительные файлы, которые нужны Dockerfile

Во время сборки flowforge переключается в SOT_BRANCH, обычно <branch>-artefacts, и создаёт там сгенерированные файлы:

  • Dockerfile.<branch>
  • info.<branch>.yaml
  • для versioned k8s-образов: info.<branch>.<version>.yaml

Скрипт формирует и добавляет файлы Dockerfile.<branch> в ветку <branch>-artefacts до отправки заданий на сборку в altflow, так как altflow ориентируется на данные файлы при сборке. Общая схема работы altflow описана в документации altflow.

В artefacts-ветке info.*.yaml хранит зафиксированные версии бинарных пакетов, полученные из repoteka после успешной сборки. При следующем запуске flowforge сравнивает эти версии с актуальными версиями пакетов и решает, какие образы устарели.

Из этого следует правило:

  • в рабочую ветку нельзя добавлять Dockerfile.<branch> и info.*.yaml;
  • в artefacts-ветке эти файлы должны сохраняться, потому что это source of truth для rebuild-логики;
  • если меняется info.yaml, cron rebuild подтягивает рабочую ветку в соответствующую artefacts-ветку merge'ом, чтобы сохранить старые слепки версий и обновить шаблоны.

Важно различать два сценария:

  • cron rebuild должен сохранять существующие info.*.yaml, потому что они нужны для сравнения версий пакетов;
  • PR-проверка новых образов постоянно пересоздаёт ci/pr-<number>-artefacts, потому что проверяет только новые спецификации из diff.

is_versioned

Бинарная спец опция для k8s-core, которая позволяет обозначить, что есть несколько версий пакета который нужно собрать.

Версии указываются в cfg/k8s-versions.json

Возможно в дальнейшем, опция будет расширена по функционалу, например для подержки сборки нескольких версий одного пакета вне k8s-core

target_package

Обязательная опция в конфигурации всех образов, кроме перечисленных в org/base. Может быть null или названием бинарного пакета.

Предназначение

От этого пакета будет унаследована версия в тэге образа. При null будет выставлен тэг соответсвующий дате сборки.

Для образов, которые собираются через DistrolessImage, версия target_package сейчас не используется как тег. Такие образы получают теги latest и дату запуска в формате YYYYMMDD.

binary_packages

Опция которая содержит список бинарных пакетов, зависимость от которых есть у данного образа.

Предназначение

  1. Слепки версий при сборке будут храниться в репозитории, для обнаружения обновлений, и устранения пересборки не устаревших образов.
  2. Если в Dockerfile.template используется {{ install_packages() }} без аргументов, будут установлены пакеты из binary_packages.

Если install_packages() вызван с явными аргументами, устанавливаются именно эти аргументы, а не перечисленные в binary_packages.

Если binary_packages указан в info.yaml, но Dockerfile.template не вызывает install_packages(), а builder.reinstall_packages и rootfs.packages не используют макрос @binary_packages для отсылки к списку binary_packages, список используется только для проверки версий и обновления artefacts. Это справедливо для обычных образов из org/alt, org/k8s-extra, org/kubevirt, для K8sImage из org/k8s-core, а также для недистролессных образов из org/base.

source_images

Локальные source-образы, которые flowforge должен учитывать как зависимости сборки.

Предназначение

  1. Проверка, что зависимость от source-образа известна flowforge
  2. Расчёт уровней сборки по графу зависимостей
  3. Пересборка зависимого образа, если его source-образ был собран в текущем запуске

В info.*.yaml flowforge может добавить служебный флаг source_images_updated. Он означает, что образ уже был поставлен в очередь из-за обновления source-образа, но ещё не был успешно собран. Вручную задавать этот флаг в info.yaml не нужно.

Если образ наследуется от обычного {{ registry }}{{ branch }}/{{ alt_image }}:latest, указывается:

source_images:
  - alt

Если образ наследуется от другого образа из org и этот образ тоже собирается flowforge, указывается canonical name:

source_images:
  - base/distroless-python3

Неизвестный в рамках flowforge source image считается ошибкой.

exclude_archs

Опциональный список архитектур, для которых образ не нужно отправлять в altflow. Возможные исключения: x86_64, aarch64, i586, loongarch64, riscv64. Для org/k8s-core рядом с архитектурой можно через запятую указать версии Kubernetes, для которых действует исключение.

Пример:

exclude_archs:
  - riscv64
  - loongarch64,1.33,1.34

exclude_branches

Опциональный список веток пакетной базы, для которых образ не нужно собирать. Исключение применяется до запросов к repoteka и до отправки задач в altflow.

Пример:

exclude_branches:
  - p10
  - c10f1

annotations

Опциональный словарь OCI annotations, который отправляется в altflow вместе с build payload.

Пример:

annotations:
  org.opencontainers.image.source: 'https://github.com/kubevirt/kubevirt'
  org.opencontainers.image.licenses: Apache-2.0
  org.opencontainers.image.vendor: 'ALT Linux Team'

altflow_context

Опциональный раздел для образов, где контекст для сборки образа (build context или buildContextPath) лежит в другом git-репозитории. Dockerfile при этом всё равно генерируется автоматически алгоритмом flowforge на основе конфигурационных файлов и не зависит от базового репозитория с основной кодовой базой.

Пример:

altflow_context:
  buildContextPath: "."
  buildGitBranch: "alt"
  git_url: "https://altlinux.space/cloud/cilium-envoy.git"

distroless

Опциональный раздел для образов, которые должны собираться через DistrolessImage. В org/k8s-core этот renderer пока не используется: там один каталог разворачивается в несколько Kubernetes-версий через K8sImage.

Основные секции:

  • from -> базовый образ финальной стадии. По умолчанию scratch
  • builder.reinstall_packages -> пакеты, которые должны быть установлены в builder-стадии
  • rootfs.files -> файлы, которые надо положить в rootfs без поиска библиотек
  • rootfs.library_files -> файлы, для которых надо добавить runtime libraries
  • rootfs.packages -> пакеты, файлы которых надо добавить в rootfs
  • rootfs.library_packages -> пакеты, для файлов которых надо добавить runtime libraries
  • rootfs.timezone -> timezone, для которой будет создан /etc/localtime
  • env -> ENV в финальном образе
  • user -> USER в финальном образе
  • workdir или workingdir -> WORKDIR в финальном образе
  • entrypoint -> JSON ENTRYPOINT
  • cmd -> JSON CMD

В builder.reinstall_packages и rootfs.packages указываются пакеты, которые нужны distroless-сборке:

distroless:
  builder:
    reinstall_packages:
      - python3
      - python3-base
  rootfs:
    packages:
      - python3
      - python3-base

altflow-test

Файл altflow-test обязателен в каждом каталоге образа. Файл не должен быть пустым, а его содержимое должно быть JSON-списком списков.

Минимально допустимый формат:

[]

Для образов, где необходимо протестировать один etrtypoint, допустим формат:

[
  "/usr/bin/python3",
  "--version"
]

Для тестирования нескольких etrypoints, используйте:

[
  [
    "/usr/bin/python3",
    "--version"
  ],
  [
    "/usr/bin/pytest3",
    "--version"
  ]
]

В случаях, когда образ собирается для нескольких архитектур и для каждой требуется уникальное тестирование, используйте формат:

{
  "amd64": [
    [
      "/usr/lib64/ld-linux-x86-64.so.2",
      "--help"
    ]
  ],
  "arm64": [
    [
      "/usr/lib64/ld-linux-aarch64.so.1",
      "--help"
    ]
  ],
  "all": [
    [
      "/usr/lib/ld-linux.so.2",
      "--help"
    ]
  ]
}

Маркер all здесь буквально говорит алгоритму протестируй следующие entrypoints для всех оставшихся не указанных явно архитектур.

Каждый вложенный список является командой для altflow test entrypoint: первый элемент - executable, остальные элементы - аргументы.

Для distroless и controller-like образов лучше проверять существование entrypoint или использовать безопасные --version/--help, которые не требуют kubernetes cluster и не запускают бесконечный процесс.