О гитерминизме
Для обеспечения согласованности и гарантии воспроизводимости 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, но мы рекомендуем еще раз подумать о возможных последствиях.
Использование сборочных секретов
Использование секретов усложняет совместное использование и воспроизводимость конфигурации в заданиях CI и среди разработчиков.
Чтобы управлять секретами и обеспечить их согласованное использование, в файле werf-giterminism.yaml можно настроить:
allowEnvVariables— разрешение использования определённых переменных окружения.allowFiles— доступ к секретам из указанных файлов.allowValueIds— использование произвольных значений секретов по идентификаторам.
Мы рекомендуем еще раз подумать о возможных последствиях и не использовать секреты без реальной необходимости.
Развёртывание
Опция –use-custom-tag
Использование алиасов тегов с неизменяемыми значениями (например, %image%-master) делает предыдущие выкаты невоспроизводимыми и требует указания политики imagePullPolicy: Always для каждого образа при конфигурации контейнеров приложения в Helm-чарте.
Для активации опции --use-custom-tag необходимо использовать werf-giterminism.yaml, но мы рекомендуем еще раз подумать о возможных последствиях.
