Конфигурация проекта

Основы

Delivery следует принципам подхода IaC (Infrastructure as Code) и стимулирует пользователя хранить конфигурацию доставки проекта вместе с кодом приложения в Git и осознанно использовать внешние зависимости. Отвечает за это механизм под названием гитерминизм.

Типовая конфигурация проекта состоит из нескольких файлов:

• werf.yaml;
• одного или нескольких Dockerfile-файлов;
• Helm-чарта.

werf.yaml

Главный конфигурационный файл проекта в Delivery. Его основное предназначение — связывание инструкций для сборки и развёртывания.

Инструкции для сборки

Определяются для каждого компонента приложения. Представлены в формате Dockerfile-файлов.

Инструкции развёртывания

Определяются для всего приложения (и всех окружений развёртывания) и должны быть представлены в виде Helm-чарта.

Пример типовой конфигурации проекта

# werf.yaml
project: app
configVersion: 1
---
image: backend
context: backend
dockerfile: Dockerfile
---
image: frontend
context: frontend
dockerfile: Dockerfile

$ tree -a
.
├── .helm
│   ├── templates
│   │   ├── NOTES.txt
│   │   ├── _helpers.tpl
│   │   ├── deployment.yaml
│   │   ├── hpa.yaml
│   │   ├── ingress.yaml
│   │   ├── service.yaml
│   │   └── serviceaccount.yaml
│   └── values.yaml
├── backend
│   ├── Dockerfile
│   └── ...
├── frontend
│   ├── Dockerfile
│   └── ...
└── werf.yaml

Гитерминизм

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

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

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

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

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

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

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

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

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

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

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

env

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

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

Сборка

Dockerfile-образ

contextAddFiles

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

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

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

Опция –use-custom-tag

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

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