title | permalink | description | toc |
---|---|---|---|
werf.yaml |
reference/werf_yaml.html |
Пример конфигурации werf |
false |
{% include reference/werf_yaml/table.html %}
Имя проекта должно быть уникальным в пределах группы проектов, собираемых на одном сборочном узле и развертываемых на один и тот же кластер Kubernetes (например, уникальным в пределах всех групп одного GitLab).
Имя проекта должно быть не более 50 символов, содержать только строчные буквы латинского алфавита, цифры и знак дефиса.
ВНИМАНИЕ. Никогда не меняйте имя проекта в процессе работы, если вы не осознаете всех последствий.
Смена имени проекта приводит к следующим проблемам:
- Инвалидация сборочного кэша. Все образы должны быть собраны повторно, а старые удалены из локального хранилища или container registry вручную.
- Создание совершенно нового Helm-релиза. Смена имени проекта и повторное развертывание приложения приведет к созданию еще одного экземпляра, если вы уже развернули ваше приложение в кластере Kubernetes.
werf не поддерживает изменение имени проекта и все возникающие проблемы должны быть разрешены вручную.
Директива позволяет указать произвольную директорию до helm чарта проекта, например .deploy/chart
:
deploy:
helmChartDir: .deploy/chart
werf позволяет определять пользовательский шаблон имени Helm-релиза, который используется во время [процесса деплоя]({{ "/advanced/helm/releases/naming.html#имя-релиза" | true_relative_url }}) для генерации имени релиза:
project: PROJECT_NAME
configVersion: 1
deploy:
helmRelease: TEMPLATE
helmReleaseSlug: false
В качестве значения для deploy.helmRelease
указывается Go-шаблон с разделителями [[
и ]]
. Поддерживаются функции [[ project ]]
, [[ env ]]
и [[ namespace ]]
. Значение шаблона имени релиза по умолчанию: [[ project ]]-[[ env ]]
.
Можно комбинировать переменные доступные в Go-шаблоне с переменными окружения следующим образом:
{% raw %}
deploy:
helmRelease: >-
[[ project ]]-[[ namespace ]]-[[ env ]]-{{ env "HELM_RELEASE_EXTRA" }}
{% endraw %}
Замечание Использование переменной окружения HELM_RELEASE_EXTRA
в данном случае должно быть явно разрешено в конфиге [werf-giterminism.yaml]({{ "reference/werf_giterminism_yaml.html" | true_relative_url }}).
deploy.helmReleaseSlug
включает или отключает [слагификацию]({{ "/advanced/helm/releases/naming.html#слагификация-имени-релиза" | true_relative_url }}) имени Helm-релиза (включен по умолчанию).
werf позволяет определять пользовательский шаблон namespace в Kubernetes, который будет использоваться во время [процесса деплоя]({{ "/advanced/helm/releases/naming.html#namespace-в-kubernetes" | true_relative_url }}) для генерации имени 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
включает или отключает [слагификацию]({{ "/advanced/helm/releases/naming.html#слагификация-namespace-kubernetes" | true_relative_url }}) имени namespace Kubernetes. Включен по умолчанию.
Конфигурация очистки состоит из набора политик, keepPolicies
, по которым выполняется выборка значимых образов на основе истории git. Таким образом, в результате [очистки]({{ "advanced/cleanup.html#очистка-неактуальных-данных" | true_relative_url }}) неудовлетворяющие политикам образы удаляются.
Каждая политика состоит из двух частей:
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
Разберём каждую политику по отдельности:
- Сохранять по одному образу для 10 последних тегов (по дате создания).
- Сохранять по не более чем два образа, опубликованных за последнюю неделю, для не более 10 веток с активностью за последнюю неделю.
- Сохранять по 10 образов для веток main, master, staging и production.
Для корректной работы сборщика 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: string
, с которой начинается описание образа в конфигурации.
image: frontend
Если в файле конфигурации описывается только один образ, то он может быть безымянным:
image: ~
Если в файле конфигурации описывается более одного образа, то каждый образ должен иметь собственное имя:
image: frontend
...
---
image: backend
...
Образ может иметь несколько имен, указываемых в виде YAML-списка (это эквивалентно описанию нескольких одинаковых образов с разными именами):
image: [main-front,main-back]
Имя образа требуется при использовании в helm-шаблонах, а также при запуске команд для определённого образа, описанного в werf.yaml
.
Сборка образа с использованием имеющегося 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
Контекст сборки Dockerfile-образа включает файлы, которые содержатся в директории, заданной директивой context
(по умолчанию это директория проекта), из текущего коммита репозитория проекта.
Директива contextAddFiles
позволяет дополнить контекст сборки произвольными файлами из директории проекта.
image: app
context: app
contextAddFiles:
- file1
- dir1/
- dir2/file2.out
В данной конфигурации контекст сборки будет состоять из следующих файлов:
app/**/*
из текущего коммита репозитория проекта;- Файлы
app/file1
,app/dir2/file2.out
и директорияdir1
, которые находятся в директории проекта.
Файлы contextAddFiles
имеют больший приоритет, чем файлы из репозитория проекта, поэтому при пересечении пользователь будет работать с ними.
По умолчанию, использование директивы
contextAddFiles
запрещено гитерминизмом (подробнее об этом в [статье]({{ "/advanced/giterminism.html#contextaddfiles" | true_relative_url }}))
Альтернативный способ сборки образов с использованием т.н. сборщика Stapel. Его особенности:
- Обеспечивает интеграцию с git и инкрементальную пересборку с учетом истории git-репозитория.
- Позволяет описывать инструкции сборки с помощью Ansible-заданий.
- Позволяет использовать между сборками общий кэш, с помощью монтирования.
- Позволяет уменьшить конечный размер образа, исключая из него исходный код и инструменты сборки.