О гитерминизме

Для обеспечения согласованности и гарантии воспроизводимости werf вводит механизм гитерминизма. Его название происходит от совмещения слов git и determinism, что можно понимать как режим «детерминированный Git». Конфигурацию и сборочный контекст werf читает из текущего коммита репозитория проекта, а также по умолчанию не позволяет использовать внешние зависимости.

Любое отступление пользователя от гитерминизма должно фиксироваться в специальном файле werf-giterminism.yaml, чтобы процесс управления конфигурацией был осмысленным, а использование прозрачным для всех участников доставки.

Исключение неиспользуемых файлов

werf не позволяет работать с незакоммиченными и неотслеживаемыми файлами в Git. Если файлы не требуются, то их следует явно исключать с помощью файлов .gitignore и .helmignore.

Использование незакоммиченных и неотслеживаемых файлов при отладке и разработке

При отладке и разработке изменение файлов проекта может доставлять неудобства за счёт необходимости создания промежуточных коммитов. Мы работаем над режимом разработки, чтобы упростить этот процесс и в то же время оставить всю логику работы неизменной.

В текущих версиях режим разработки (активируется опцией --dev) позволяет работать с состоянием worktree Git-репозитория проекта, с отслеживаемыми (tracked) и неотслеживаемыми (untracked) файлами. werf игнорирует изменения с учётом правил, описанных в .gitignore, а также правил, заданных пользователем опцией --dev-ignore=<glob> (может использоваться несколько раз).

Выборочное разрешение недетерминированной функциональности

Шаблонизация werf.yaml

Функции Go-шаблонизатора

env

Использование функции env усложняет совместное использование и воспроизводимость конфигурации в заданиях CI и среди разработчиков, поскольку значение переменной среды влияет на окончательный дайджест собираемых образов. Значение должно быть идентичным на всех этапах CI-пайплайна и во время локальной разработки при воспроизведении.

Для активации функции env необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.

Сборка

Dockerfile-образ

contextAddFiles

Использование директивы contextAddFiles усложняет совместное использование и воспроизводимость конфигурации в заданиях CI и среди разработчиков, поскольку данные файла влияют на окончательный дайджест собираемых образов и должны быть идентичными на всех этапах CI-пайплайна и во время локальной разработки при воспроизведении.

Для активации директивы contextAddFiles необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.

Stapel-образ

fromLatest

При использовании fromLatest werf начинает учитывать реальный дайджест базового образа в дайджесте собираемого образа. Таким образом, использование этой директивы может нарушить воспроизводимость предыдущих сборок. Изменение базового образа в container registry делает непригодными для использования все ранее собранные образы.

  • Предыдущие задания CI-пайплайна (например, converge) не могут быть выполнены повторно без пересборки образа после изменения базового образа в container registry.
  • Изменение базового образа в container registry приводит к неожиданным падениям CI-пайплайна. Например, изменение происходит после успешной сборки, и следующие задания не могут выполниться из-за изменения дайджеста конечных образов вместе с дайджестом базового образа.

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

Для активации директивы fromLatest необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.

git
branch

Использование ветки (по умолчанию ветка master) при работе с произвольными Git-репозиториями может нарушить воспроизводимость предыдущих сборок. werf использует историю Git-репозитория для расчета дайджеста собираемого образа. Таким образом, новый коммит в ветке делает непригодным для использования все ранее собранные образы.

  • Существующие задания CI-пайплайна (например, converge) не будут выполняться и потребуют пересборки образа, если HEAD ветки был изменён.
  • Неконтролируемые коммиты в ветку могут приводить к сбоям CI-пайплайна без видимых причин. Например, изменения могут произойти после успешного завершения процесса сборки. В этом случае связанные задания CI-пайплайна завершатся с ошибкой из-за изменений в дайджестах собираемых образов вместе с HEAD связанной ветки.

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

Для активации директивы branch необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.

mount
build_dir

Использование монтирования build_dir может приводить к непредсказуемому поведению при параллельном использовании и потенциально повлиять на воспроизводимость и надежность.

Для активации директивы build_dir необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.

fromPath

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

Для активации директивы fromPath необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.

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

Опция –use-custom-tag

Использование алиасов тегов с неизменяемыми значениями (например, %image%-master) делает предыдущие выкаты невоспроизводимыми и требует указания политики imagePullPolicy: Always для каждого образа при конфигурации контейнеров приложения в Helm-чарте.

Для активации опции --use-custom-tag необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.