Справочник

werf.yaml

# Секция мета-информации
---
# Уникальное имя проекта приложения
project: string
# Версия конфигурации. На данный момент поддерживается единственная версия 1
configVersion: int
build: # Общие настройки сборки
  # Общий список целевых платформ для всех образов (например ['linux/amd64', 'linux/arm64',
  # 'linux/arm/v8'])
  platform: [ string, ... ]
deploy: # Настройки выката
  # Путь до директории helm чарта проекта (значение по умолчанию .helm)
  helmChartDir: string
  # Шаблон имени релиза (значение по умолчанию [[ project ]]-[[ env ]])
  helmRelease: string
  # Слагификация имени релиза (значение по умолчанию true)
  helmReleaseSlug: bool
  # Шаблон Kubernetes namespace (значение по умолчанию [[ project ]]-[[ env ]])
  namespace: string
  # Слагификация Kubernetes namespace (значение по умолчанию true)
  namespaceSlug: bool
# Настройка удаления неактульных образов
cleanup:
  # Отключить политику очистки, которая позволяет не удалять запущенные в Kubernetes образы из 
  # container registry
  disableKubernetesBasedPolicy: bool
  # Отключить политику очистки, которая позволяет не удалять образы с учётом пользовательских 
  # политик по истории Git (keepPolicies)
  disableGitHistoryBasedPolicy: bool
  # Отключить политику очистки, которая позволяет не удалять образы, собранные в рамках заданного 
  # периода времени (keepImagesBuiltWithinLastNHours)
  disableBuiltWithinLastNHoursPolicy: bool
  # Минимальное количество часов, которое должно пройти с момента сборки образа (значение по 
  # умолчанию 2)
  keepImagesBuiltWithinLastNHours: uint
  # Набор политик для выборки актуальных образов, используя историю Git
  keepPolicies:
  # Набор references, который будет использоваться при сканировании
  - references:
      # Множество git origin веток
      branch: string || /REGEXP/
      # Множество git origin тегов
      tag: string || /REGEXP/
      # Набор правил, по которым можно ограничить описанное множество references, основываясь на 
      # времени создания git-тега или активности в git-ветке
      limit:
        # Выборка последних n references из определённого в branch/tag множества (значение по 
        # умолчанию -1)
        last: int
        # Выборка git-тегов, которые были созданы в указанный период, или git-веток с активностью 
        # в рамках периода. Также для определённого множества branch/tag
        in: duration string
        # Определяет какие references будут результатом политики, те которые удовлетворяют оба 
        # условия или любое из них (значение по умолчанию And)
        operator: And || Or
    # Лимит искомых образов для каждого reference из множества
    imagesPerReference:
      # Количество искомых образов для каждого reference (значение по умолчанию -1)
      last: int
      # Период, в рамках которого необходимо выполнять поиск образов
      in: duration string
      # Определяет какие образы сохранятся после применения политики, те которые удовлетворяют оба 
      # условия или любое из них (значение по умолчанию And)
      operator: And || Or
# Настройки связанные с работой Delivery с рабочей директорией git проекта
gitWorktree:
  # Принудительно позволить Delivery использовать shallow clone несмотря на ограничения 
  # данного подхода
  forceShallowClone: bool
  # Разрешить процессу Delivery автоматически преобразовать shallow clone проекта в 
  # полный clone в процессе сборки по необходимости (значение по умолчанию true)
  allowUnshallow: bool
  # Разрешить процессу Delivery автоматически скачать новые ветки и теги из origin в 
  # процессе cleanup по необходимости (значение по умолчанию true)
  allowFetchOriginBranchesAndTags: bool
# Секция Dockerfile image: может использоваться произвольное количество секций
---
# Одно или несколько уникальных имён для образа
image: string || [ string, ... ] || ~
# Путь к Dockerfile относительно директории контекста
dockerfile: string
# Включить послойное кеширование Dockerfile-инструкций в container registry
staged: bool
# Путь к контексту внутри папки проекта
context: string
# Список целевых платформ для данного образа (например ['linux/amd64', 'linux/arm64', 
# 'linux/arm/v8'])
platform: [ string, ... ]
# Добавление нехранящихся в git файлов и директорий в сборочный контекст. Пути должны быть 
# относительно директории контекста
contextAddFiles: [ string, ... ]
# Конкретная стадия Dockerfile (по умолчанию — последняя, подобно docker build --target)
target: string
# Переменные для ARG Dockerfile-инструкций (подобно docker build --build-arg)
args: { name string: value string, ... }
# Установить связь host-to-IP (host:ip) (подобно docker build --add-host)
addHost: [ string, ... ]
# Сетевой режим для инструкций RUN во время сборки (подобно docker build --network)
network: string
# Сокет агента SSH или ключи для сборки определённых слоёв (только если используется BuildKit) 
# (подобно docker build --ssh)
ssh: string
# Образы-зависимости для текущего образа
dependencies:
# Имя зависимого образа, который должен быть собран до сборки текущего образа
- image: string
  # Определить аргументы для импорта информации о зависимом образе в текущий образ используя 
  # Dockerfile build-args (опционально)
  imports:
  # Тип импортируемой информации об образе: ImageName, ImageDigest, ImageRepo или ImageTag
  - type: string
    # Имя аргумента (Dockerfile build-args), который будет содержать указанный тип информации об 
    # образе
    targetBuildArg: string
# Набор директив для изменения манифеста образа.
docker:
  # Включить использование незаэкранированных символов (например кавычки и пробелы) в значениях 
  # опций.
  exactValues: bool
  # Имя пользователя (или UID) и опционально пользовательская группа (или GID).
  USER: string
  # Рабочая директория.
  WORKDIR: string
  # Точки монтирования.
  VOLUME: [ string, ... ]
  # Переменные окружения.
  ENV: { name string: value string, ... }
  # Метаданные.
  LABEL: { name string: value string, ... }
  # Описание сетевых портов, которые будут прослушиваться в запущенном контейнере.
  EXPOSE: [ string, ... ]
  # Команда по умолчанию, которая будет выполнена при запуске контейнера (форма записи shell или 
  # exec).
  ENTRYPOINT: string | [ string, ... ]
  # Аргументы по умолчанию для ENTRYPOINT (форма записи shell или exec).
  CMD: string | [ string, ... ]
  # Инструкции, которые Docker может использовать для проверки работоспособности запущенного 
  # контейнера.
  HEALTHCHECK: string
# Точки монтирования.
mount:
# Имя служебной директории
- from: tmp_dir || build_dir
  # Абсолютный или относительный путь до произвольного файла на хосте
  fromPath: string
  # Абсолютный путь в образе
  to: string
# Импортирование из образов и артефактов.
import:
# Имя артефакта, из которого выполнять копирование файлов
- artifact: string
  # Имя образа, из которого выполнять копирование файлов
  image: string
  # Имя стадии, из которой выполнять копирование файлов (по умолчанию последняя)
  stage: string
  # Выбор стадии импортирования файлов при сборке, до стадии install или setup
  before: string
  # Выбор стадии импортирования файлов при сборке, после стадии install или setup
  after: string
  # Абсолютный путь до файла или директории в выбранном образе/артефакте
  add: string
  # Абсолютный путь в конечном образе. По умолчанию соответствует пути add
  to: string
  # Имя или UID владельца
  owner: string
  # Имя или GID группы
  group: string
  # Глобы добавления
  includePaths: [ glob, ... ]
  # Глобы исключения
  excludePaths: [ glob, ... ]
# Образы-зависимости для текущего образа
dependencies:
# Имя зависимого образа, который должен быть собран до сборки текущего образа
- image: string
  # Выбор стадии перед которой должна быть импортирована информация об образе (требуется указать 
  # install или setup). Указанные переменные окружения будут доступны в пользовательских стадиях 
  # после указанной данной директивой стадии.
  before: string
  # Выбор стадии после которой должна быть импортирована информация об образе (требуется указать 
  # install или setup). Указанные переменные окружения будут доступны в пользовательских стадиях 
  # после указанной данной директивой стадии.
  after: string
  # Определить аргументы для импорта информации о зависимом образе в текущий образ используя 
  # переменные окружения (опционально)
  imports:
  # Тип импортируемой информации об образе: ImageName, ImageDigest, ImageRepo или ImageTag
  - type: string
    # Имя переменной окружения, которая будет содержать указанный тип информации об образе
    targetEnv: string

werf-giterminism.yaml

# Версия конфигурации. На данный момент поддерживается единственная версия 1
giterminismConfigVersion: int
# Правила ослабления гитерминизма для CLI
cli:
  # Разрешить опцию --use-custom-tag
  allowCustomTags: bool
# Правила ослабления гитерминизма для конфигурации Delivery (werf.yaml)
config:
  # Читать конфигурационный файл из директории проекта, не сверяя контент с файлом из текущего 
  # коммита и игнорируя исключения в .gitignore
  allowUncommitted: bool
  # Читать определённые шаблоны конфигурационного файла (.werf/**/*.tmpl) из директории проекта, 
  # не сверяя контент с файлами текущего коммита и игнорируя исключения в .gitignore
  allowUncommittedTemplates: [ glob, ... ]
  # Правила для функций Go-шаблонизатора
  goTemplateRendering:
    # Разрешить определённые переменные окружения (при использовании функции env).
    allowEnvVariables: [ string || /REGEXP/, ... ]
    # Читать определённые конфигурационные файлы из директории проекта, не сверяя контент с 
    # файлами текущего коммита и игнорируя исключения в .gitignore (используя функции .Files.Get и 
    # .Files.Glob)
    allowUncommittedFiles: [ glob, ... ]
  # Правила для dockerfile-образа
  dockerfile:
    # Читать определённые dockerfiles из директории проекта, не сверяя контент с файлами текущего 
    # коммита и игнорируя исключения в .gitignore
    allowUncommitted: [ glob, ... ]
    # Читать определённые .dockerignore-файлы из директории проекта, не сверяя контент с файлами 
    # текущего коммита и игнорируя исключения в .gitignore
    allowUncommittedDockerignoreFiles: [ glob, ... ]
    # Разрешить использование определённых файлов или директорий из директории проекта при 
    # использовании директивы contextAddFiles.
    allowContextAddFiles: [ string, ... ]
# Правила ослабления гитерминизма для helm-файлов (.helm)
helm:
  # Читать определённые helm-файлы из директории проекта, не сверяя контент с файлами текущего 
  # коммита и игнорируя исключения в .gitignore
  allowUncommittedFiles: [ glob, ... ]

Шаблонизатор werf.yaml

При чтении конфигурации werf.yaml, Delivery использует встроенный движок шаблонов Go (text/template), а также расширяет набор функций с помощью Sprig и функций Delivery.

При организации конфигурации она может быть разбита на отдельные файлы в директории шаблонов.

Встроенные возможности шаблонизатора Go

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

• Actions, основные возможности шаблонизатора.
• Переменные.
• Работа с текстом и пробелами.
• Функции.

Функции Sprig

Библиотека Sprig предоставляет более 70 функций:

• Строковые функции.
• Математические функции.
• Функции кодирования.
• Работа с данными в формате ключ/значение (dict).
• Работа с файловыми путями.
• Остальное.

Delivery не поддерживает функцию expandenv и имеет свою собственную реализацию для функции env.

Функции Delivery

Различные окружения

.Env

Переменная .Env позволяет организовывать конфигурацию для нескольких сред (testing, staging, production и т.п.) и переключаться между ними с помощью опции --env=<environment_name>.

В helm шаблонах таким же образом может использоваться переменная .Values.werf.env.

Информация о текущем коммите

.Commit.Hash

{{ .Commit.Hash }} возвращает SHA текущего коммита. Если есть возможность, лучше избегать использование .Commit.Hash, т. к. это может приводить к ненужным пересборкам слоев.

.Commit.Date

{{ .Commit.Date.Human }} возвращает дату текущего коммита в человекопонятной форме.

{{ .Commit.Date.Unix }} возвращает дату текущего коммита в формате Unix epoch.

Шаблонизация

include

Функция include позволяет переиспользовать общие части конфигурации, а также разбивать конфигурацию на несколько файлов.

Синтаксис:

{{ include "<TEMPLATE_NAME>" <VALUES> }}

tpl

Функция tpl позволяет обрабатывать строки как Go-шаблоны.

Синтаксис:

{{ tpl "<STRING>" <VALUES> }}

• <STRING> — контент файла проекта, значение переменной окружения либо произвольная строка.
• <VALUES> — значения шаблона. При использовании текущего контекста, ., в шаблоне можно использовать все шаблоны и значения (в том числе, описанные в файлах директории шаблонов).

Переменные окружения

env

Функция env читает переменную окружения.

Синтаксис:

{{ env "<ENV_NAME>" }}
{{ env "<ENV_NAME>" "default_value" }}

По умолчанию, использование функции env запрещено гитерминизмом

Файлы проекта

.Files.Get

Функция .Files.Get получает содержимое определенного файла проекта.

Синтаксис:

{{ .Files.Get "<FILE_PATH>" }}

По умолчанию, использование файлов, которые имеют незакоммиченные изменения, запрещено гитерминизмом

.Files.Glob

Функция .Files.Glob позволяет работать с файлами проекта и их содержимым по глобу.

Функция поддерживает shell pattern matching и **. Результаты вызова функции можно объединить, используя sprig-функцию merge (к примеру, {{ $filesDict := merge (.Files.Glob "glob1") (.Files.Glob "glob2") }})

Синтаксис:

{{ .Files.Glob "<GLOB>" }}

По умолчанию, использование файлов, которые имеют незакоммиченные изменения, запрещено гитерминизмом

Другие

required

Функция required проверяет наличие значения у определённой переменной. Если значение пусто, то рендеринг шаблона завершится ошибкой с заданным пользователем сообщением.

Синтаксис:

value: {{ required "<ERROR_MSG>" <VALUE> }}

fromYaml

Функция fromYaml декодирует YAML-документ в структуру.

Синтаксис:

value: {{ fromYaml "<STRING>" }}

Директория шаблонов

Файлы шаблонов могут храниться в зарезервированной директории (по умолчанию .werf) с расширением .tmpl (поддерживается произвольная вложенность .werf/**/*.tmpl).

Все файлы шаблонов и основная конфигурация определяют общий контекст:

• Файл шаблонов является полноценным шаблоном и может использоваться функцией include по относительному пути ({{ include "directory/partial.tmpl" . }}).
• Шаблон определённый с помощью define в одном файле шаблонов доступен в любом другом, включая основную конфигурацию.

Аннотации для деплоя

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

• werf.io/weight — задает вес ресурса, который определяет порядок развертывания ресурсов.
• <any-name>.external-dependency.werf.io/resource — дождаться, пока указанная внешняя зависимость будет запущена, и только после этого приступить к развертыванию аннотированного ресурса.
• <any-name>.external-dependency.werf.io/namespace — задать пространство имен для внешней зависимости.
• werf.io/replicas-on-creation — задаёт количество реплик, которое должно быть установлено при первичном создании ресурса (полезно при использовании HPA).
• werf.io/track-termination-mode — определяет условие при котором Delivery остановит отслеживание ресурса.
• werf.io/fail-mode — определяет как Delivery обработает ресурс в состоянии ошибки. Ресурс в свою очередь перейдет в состояние ошибки после превышения порога допустимых ошибок, обнаруженных при отслеживании этого ресурса в процессе выката.
• werf.io/failures-allowed-per-replica — определяет порог ошибок, обнаруживаемых при отслеживании этого ресурса в процессе выката, после превышения которого ресурс перейдет в состояние ошибки. Delivery обработает это состояние в соответствии с настройкой fail mode.
• werf.io/ignore-readiness-probe-fails-for-CONTAINER_NAME — переопределить высчитываемый автоматически период, в течение которого неуспешные readiness-пробы будут игнорироваться и не будут переводить ресурс в состояние ошибки.
• werf.io/no-activity-timeout — переопределить период неактивности, по истечении которого ресурс перейдет в состояние ошибки.
• werf.io/log-regex — показывать в логах только те строки вывода ресурса, которые подходят под указанный шаблон.
• werf.io/log-regex-for-CONTAINER_NAME — показывать в логах только те строки вывода для указанного контейнера, которые подходят под указанный шаблон.
• werf.io/skip-logs — выключить логирование вывода для ресурса.
• werf.io/skip-logs-for-containers — выключить логирование вывода для указанного контейнера.
• werf.io/show-logs-only-for-containers — включить логирование вывода только для указанных контейнеров ресурса.
• werf.io/show-service-messages — включить вывод сервисных сообщений и событий Kubernetes для данного ресурса.

Resource weight

werf.io/weight: "NUM"

Пример:
werf.io/weight: "10"
werf.io/weight: "-10"

Может быть положительным числом, отрицательным числом или нулем. Значение передается в виде строки. По умолчанию weight имеет значение 0. Работает только для ресурсов, не относящихся к хукам. Для хуков используйте helm.sh/hook-weight, логика работы которого почти такая же.

Этот параметр задает вес ресурсов, определяя порядок их развертывания. Сначала Delivery группирует ресурсы в соответствии с их весом, а затем последовательно развертывает их, начиная с группы с наименьшим весом. В этом случае Delivery не будет приступать к развертыванию следующей группы ресурсов, пока развертывание предыдущей не завершено успешно.

External dependency resource

<any-name>.external-dependency.werf.io/resource: type[.version.group]/name

Пример:
secret.external-dependency.werf.io/resource: secret/config
someapp.external-dependency.werf.io/resource: deployments.v1.apps/app

Задает внешнюю зависимость для ресурса. Ресурс с аннотацией будет развернут только после создания и готовности внешней зависимости.

External dependency namespace

<any-name>.external-dependency.werf.io/namespace: name

Указывает пространство имен для внешней зависимости, заданной соответствующей аннотацией. Префикс <any-name> должен быть таким же, как у аннотации, определяющей внешнюю зависимость.

Replicas on creation

Когда для ресурса включён HPA, использование spec.replicas может привести к непредсказуемому поведению, потому что каждый раз когда происходит converge для Delivery chart через CI/CD количество реплик ресурса будет сброшено к статически заданному в шаблонах чарта значению spec.replicas, даже если это значение изменил HPA в рантайме.

Одно из рекомендованных решений — совсем удалить spec.replicas из шаблонов чарта. Однако если необходимо установить начальное значение реплик при создании ресурса, можно воспользоваться аннотацией "werf.io/replicas-on-creation".

"werf.io/replicas-on-creation": "NUM"

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

ЗАМЕЧАНИЕ "NUM" должно быть указано строкой (в двойных кавычках), потому что аннотации не поддерживают передачу других типов данных кроме строк, аннотации с другим типом данных будут проигнорированы.

Track termination mode

"werf.io/track-termination-mode": WaitUntilResourceReady|NonBlocking

Определяет условие остановки отслеживания ресурса в процессе деплоя:

• WaitUntilResourceReady (по умолчанию) — весь процесс деплоя будет отслеживать и ожидать готовности ресурса с данной аннотацией. Т.к. данный режим включен по умолчанию, то, по умолчанию, процесс деплоя ждет готовности всех ресурсов.
• NonBlocking — ресурс с данной аннотацией отслеживается только пока есть другие ресурсы, готовности которых ожидает процесс деплоя.

СОВЕТ Используйте аннотации — "werf.io/track-termination-mode": NonBlocking и "werf.io/fail-mode": IgnoreAndContinueDeployProcess, когда описываете в релизе объект Job, который должен быть запущен в фоне и не влияет на процесс деплоя.

СОВЕТ Используйте аннотацию "werf.io/track-termination-mode": NonBlocking, когда описываете в релизе объект StatefulSet с ручной стратегией выката (параметр OnDelete) и не хотите блокировать весь процесс деплоя из-за этого объекта, дожидаясь его обновления.

Fail mode

"werf.io/fail-mode": FailWholeDeployProcessImmediately|HopeUntilEndOfDeployProcess|IgnoreAndContinueDeployProcess

Определяет как Delivery будет обрабатывать ресурс в состоянии ошибки, которое возникает после превышения порога ошибок, возникающих во время отслеживания данного ресурса в процессе деплоя:

• FailWholeDeployProcessImmediately (по умолчанию) — в случае ошибки при деплое ресурса с данной аннотацией, весь процесс деплоя будет завершен с ошибкой.
• HopeUntilEndOfDeployProcess — в случае ошибки при деплое ресурса с данной аннотацией его отслеживание будет продолжаться, пока есть другие ресурсы, готовности которых ожидает процесс деплоя, либо все оставшиеся ресурсы имеют такую-же аннотацию. Если с ошибкой остался только этот ресурс или несколько ресурсов с такой-же аннотацией, то в случае сохранения ошибки весь процесс деплоя завершается с ошибкой.
• IgnoreAndContinueDeployProcess — ошибка при деплое ресурса с данной аннотацией не влияет на весь процесс деплоя.

Failures allowed per replica

"werf.io/failures-allowed-per-replica": "NUMBER"

По умолчанию, при отслеживании статуса ресурса допускается срабатывание ошибки 1 раз, прежде чем весь процесс деплоя считается ошибочным. Этот параметр влияет на поведение настройки Fail mode: определяет порог срабатывания, после которого начинает работать режим реакции на ошибки.

Ignore readiness probe failures for container

"werf.io/ignore-readiness-probe-fails-for-CONTAINER_NAME": "TIME"

Эта аннотация позволяет переопределить высчитываемый автоматически период, в течение которого неуспешные readiness-пробы не станут переводить ресурс в состояние ошибки, т. е. будут проигнорированы. По умолчанию период игнорирования неудачных readiness-проб автоматически вычисляется на основе конфигурации readiness-пробы. Заметим, что если в конфигурации readiness-пробы указано failureThreshold: 1, тогда первая же неудачная readiness-проба переведет ресурс в состояние ошибки, независимо от периода игнорирования.

Формат записи значения описан здесь.

Пример: "werf.io/ignore-readiness-probe-fails-for-backend": "20s"

No activity timeout

werf.io/no-activity-timeout: "TIME"

По умолчанию: 4m

Пример:
werf.io/no-activity-timeout: "8m30s"
werf.io/no-activity-timeout: "90s"

При отсутствии новых событий и обновлений ресурса в течение TIME ресурс перейдет в состояние ошибки.

Формат записи значения описан здесь.

Log regex

"werf.io/log-regex": RE2_REGEX

Определяет Re2 regex шаблон, применяемый ко всем логам всех контейнеров всех подов ресурса с этой аннотацией. Delivery будет выводить только те строки лога, которые удовлетворяют regex-шаблону. По умолчанию Delivery выводит все строки лога.

Log regex for container

"werf.io/log-regex-for-CONTAINER_NAME": RE2_REGEX

Определяет Re2 regex шаблон, применяемый к логам контейнера с именем CONTAINER_NAME всех подов с данной аннотацией. Delivery будет выводить только те строки лога, которые удовлетворяют regex-шаблону. По умолчанию Delivery выводит все строки лога.

Skip logs

"werf.io/skip-logs": "true"|"false"

Если установлена в "true", то логи всех контейнеров пода с данной аннотацией не выводятся при отслеживании. Отключено по умолчанию.

Skip logs for containers

"werf.io/skip-logs-for-containers": CONTAINER_NAME1,CONTAINER_NAME2,CONTAINER_NAME3...

Список (через запятую) контейнеров пода с данной аннотацией, для которых логи не выводятся при отслеживании.

Show logs only for containers

"werf.io/show-logs-only-for-containers": CONTAINER_NAME1,CONTAINER_NAME2,CONTAINER_NAME3...

Список (через запятую) контейнеров пода с данной аннотацией, для которых выводятся логи при отслеживании. Для контейнеров, чьи имена отсутствуют в списке, логи не выводятся. По умолчанию выводятся логи для всех контейнеров всех подов ресурса.

Show service messages

"werf.io/show-service-messages": "true"|"false"

Если установлена в "true", то при отслеживании для ресурсов будет выводиться дополнительная отладочная информация, такая как события Kubernetes. По умолчанию, Delivery выводит такую отладочную информацию только в случае если ошибка ресурса приводит к ошибке всего процесса деплоя.