Имя проекта

Имя проекта должно быть уникальным в пределах группы проектов, собираемых на одном сборочном узле и развертываемых на один и тот же кластер Kubernetes (например, уникальным в пределах всех групп одного GitLab).

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

Последствия смены имени проекта

ВНИМАНИЕ. Никогда не меняйте имя проекта в процессе работы, если вы не осознаете всех последствий.

Смена имени проекта приводит к следующим проблемам:

  1. Инвалидация сборочного кэша. Все образы должны быть собраны повторно, а старые удалены из локального хранилища или container registry вручную.
  2. Создание совершенно нового Helm-релиза. Смена имени проекта и повторное развертывание приложения приведет к созданию еще одного экземпляра, если вы уже развернули ваше приложение в кластере Kubernetes.

werf не поддерживает изменение имени проекта и все возникающие проблемы должны быть разрешены вручную.

Выкат

Директория helm chart

Директива позволяет указать произвольную директорию до helm чарта проекта, например .deploy/chart:

deploy:
  helmChartDir: .deploy/chart

Имя релиза

werf позволяет определять пользовательский шаблон имени Helm-релиза, который используется во время процесса деплоя для генерации имени релиза:

project: PROJECT_NAME
configVersion: 1
deploy:
  helmRelease: TEMPLATE
  helmReleaseSlug: false

В качестве значения для deploy.helmRelease указывается Go-шаблон с разделителями [[ и ]]. Поддерживаются функции [[ project ]], [[ env ]] и [[ namespace ]]. Значение шаблона имени релиза по умолчанию: [[ project ]]-[[ env ]].

Можно комбинировать переменные доступные в Go-шаблоне с переменными окружения следующим образом:

deploy:
  helmRelease: >-
    [[ project ]]-[[ namespace ]]-[[ env ]]-{{ env "HELM_RELEASE_EXTRA" }}

Замечание Использование переменной окружения HELM_RELEASE_EXTRA в данном случае должно быть явно разрешено в конфиге werf-giterminism.yaml.

deploy.helmReleaseSlug включает или отключает слагификацию имени Helm-релиза (включен по умолчанию).

Namespace в Kubernetes

werf позволяет определять пользовательский шаблон namespace в Kubernetes, который будет использоваться во время процесса деплоя для генерации имени namespace.

Пользовательский шаблон namespace Kubernetes определяется в секции мета-информации в файле werf.yaml:

project: PROJECT_NAME
configVersion: 1
deploy:
  namespace: TEMPLATE
  namespaceSlug: true|false

В качестве значения для deploy.namespace указывается Go-шаблон с разделителями [[ и ]]. Поддерживаются функции project и env. Значение шаблона имени namespace по умолчанию: [[ project ]]-[[ env ]].

deploy.namespaceSlug включает или отключает слагификацию имени namespace Kubernetes. Включен по умолчанию.

Очистка

Конфигурация политик очистки

Конфигурация очистки состоит из набора политик, keepPolicies, по которым выполняется выборка значимых образов на основе истории git. Таким образом, в результате очистки неудовлетворяющие политикам образы удаляются.

Каждая политика состоит из двух частей:

  • references определяет множество references, git-тегов или git-веток, которые будут использоваться при сканировании.
  • imagesPerReference определяет лимит искомых образов для каждого reference из множества.

Любая политика должна быть связана с множеством git-тегов (tag: string || /REGEXP/) либо git-веток (branch: string || /REGEXP/). Можно указать определённое имя reference или задать специфичную группу, используя синтаксис регулярных выражений golang.

tag: v1.1.1
tag: /^v.*$/
branch: main
branch: /^(main|production)$/

При сканировании описанный набор git-веток будет искаться среди origin remote references, но при написании конфигурации префикс origin/ в названии веток опускается

Заданное множество references можно лимитировать, основываясь на времени создания git-тега или активности в git-ветке. Группа параметров limit позволяет писать гибкие и эффективные политики под различные workflow.

- references:
    branch: /^features\/.*/
    limit:
      last: 10
      in: 168h
      operator: And

В примере описывается выборка из не более чем 10 последних веток с префиксом features/ в имени, в которых была какая-либо активность за последнюю неделю.

  • Параметр last: int позволяет выбирать последние n references из определённого в branch/tag множества.
  • Параметр in: duration string (синтаксис доступен в документации) позволяет выбирать git-теги, которые были созданы в указанный период, или git-ветки с активностью в рамках периода. Также для определённого множества branch/tag.
  • Параметр operator: And || Or определяет какие references будут результатом политики, те которые удовлетворяют оба условия или любое из них (And по умолчанию).

По умолчанию при сканировании reference количество искомых образов не ограничено, но поведение может настраиваться группой параметров imagesPerReference:

imagesPerReference:
  last: int
  in: duration string
  operator: And || Or
  • Параметр last: int определяет количество искомых образов для каждого reference. По умолчанию количество не ограничено (-1).
  • Параметр in: duration string (синтаксис доступен в документации) определяет период, в рамках которого необходимо выполнять поиск образов.
  • Параметр operator: And || Or определяет какие образы сохранятся после применения политики, те которые удовлетворяют оба условия или любое из них (And по умолчанию)

Для git-тегов проверяется только HEAD-коммит и значение last >1 не имеет никакого смысла, является невалидным

При описании группы политик необходимо идти от общего к частному. Другими словами, imagesPerReference для конкретного reference будет соответствовать последней политике, под которую он подпадает:

- references:
    branch: /.*/
  imagesPerReference:
    last: 1
- references:
    branch: master
  imagesPerReference:
    last: 5

В данном случае, для reference master справедливы обе политики и при сканировании ветки last будет равен 5.

Политики по умолчанию

В случае, если в werf.yaml отсутствуют пользовательские политики очистки, используются политики по умолчанию, соответствующие следующей конфигурации:

cleanup:
  keepPolicies:
  - references:
      tag: /.*/
      limit:
        last: 10
  - references:
      branch: /.*/
      limit:
        last: 10
        in: 168h
        operator: And
    imagesPerReference:
      last: 2
      in: 168h
      operator: And
  - references:  
      branch: /^(main|master|staging|production)$/
    imagesPerReference:
      last: 10

Разберём каждую политику по отдельности:

  1. Сохранять образ для 10 последних тегов (по дате создания).
  2. Сохранять по не более чем два образа, опубликованных за последнюю неделю, для не более 10 веток с активностью за последнюю неделю.
  3. Сохранять по 10 образов для веток main, staging и production.

Git worktree

Для корректной работы сборщика stapel werf-у требуется полная git-история проекта, чтобы работать в наиболее эффективном режиме. Поэтому по умолчанию werf выполняет fetch истории для текущего git проекта, когда это требуется. Это означает, что werf может автоматически сконвертировать shallow-clone репозитория в полный clone и скачать обновлённый список веток и тегов из origin в процессе очистки образов.

Поведение по умолчанию описывается следующими настройками:

gitWorktree:
  forceShallowClone: false
  allowUnshallow: true
  allowFetchOriginBranchesAndTags: true

Чтобы, например, выключить автоматический unshallow рабочей директории git, необходимы следующие настройки:

gitWorktree:
  forceShallowClone: true
  allowUnshallow: false

Секция image

Образы описываются с помощью директивы image: image: string, с которой начинается описание образа в конфигурации.

image: frontend

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

image: ~

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

image: frontend
...
---
image: backend
...

Образ может иметь несколько имен, указываемых в виде YAML-списка (это эквивалентно описанию нескольких одинаковых образов с разными именами):

image: [main-front,main-back]

Имя образа требуется при использовании в helm-шаблонах, а также при запуске команд для определённого образа, описанного в werf.yaml.

Сборщик Dockerfile

Сборка образа с использованием имеющегося Dockerfile — самый простой путь начать использовать werf в существующем проекте. Ниже приведен пример минимального файла werf.yaml, описывающего образ example проекта:

project: my-project
configVersion: 1
---
image: example
dockerfile: Dockerfile

Также, вы можете описывать несколько образов из одного и того же Dockerfile:

image: backend
dockerfile: Dockerfile
target: backend
---
image: frontend
dockerfile: Dockerfile
target: frontend

И конечно, вы можете описывать образы, основанные на разных Dockerfile:

image: backend
dockerfile: dockerfiles/DockerfileBackend
---
image: frontend
dockerfile: dockerfiles/DockerfileFrontend

contextAddFiles

Контекст сборки Dockerfile-образа включает файлы, которые содержатся в директории, заданной директивой context (по умолчанию это директория проекта), из текущего коммита репозитория проекта.

Директива contextAddFiles позволяет дополнить контекст сборки произвольными файлами из директории проекта.

image: app
context: app
contextAddFiles:
 - file1
 - dir1/
 - dir2/file2.out

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

  • app/**/* из текущего коммита репозитория проекта;
  • Файлы app/file1, app/dir2/file2.out и директория dir1, которые находятся в директории проекта.

Файлы contextAddFiles имеют больший приоритет, чем файлы из репозитория проекта, поэтому при пересечении пользователь будет работать с ними.

По умолчанию, использование директивы contextAddFiles запрещено гитерминизмом (подробнее об этом в статье)

Stapel сборщик

Альтернативный способ сборки образов с использованием т.н. сборщика Stapel. Его особенности:

  • Обеспечивает интеграцию с git и инкрементальную пересборку с учетом истории git-репозитория.
  • Позволяет описывать инструкции сборки с помощью Ansible-заданий.
  • Позволяет использовать между сборками общий кэш, с помощью монтирования.
  • Позволяет уменьшить конечный размер образа, исключая из него исходный код и инструменты сборки.