Просто следуйте приведённым шагам, чтобы перевести ваш проект с v1.1 на v1.2.
0. Ограничение использования mounts
ВАЖНО. Существуют такие конфигурации v11, которые используют директивы mount from build_dir
и mount fromPath
для кеширования внешних зависимостей приложения (зависимости описываемые в таких файлах как Gemfile, package.json, go.mod и т.п.). Такие директивы mount
всё ещё поддерживаются в werf v1.2, однако не рекомендуется к использованию и по умолчанию выключены режимом гитерминизма (за исключением mount from tmp_dir
— данная директива не ограничена к использованию), потому что использование этих директив может привести к ненадёжным, недетерминированным сборкам, зависимым от сборочных хостов. Для таких конфигураций планируется добавление новой возможности хранения такого кеша в docker образах. Данная фича планируется к добавлению в v1.2, но еще не реализована. Поэтому, если ваша конфигурация использует такие mounts, предлагаются следующие варианты:
- Продолжить использование версии v1.1, пока данная улучшенная возможность кеширования не будет добавлена в werf v1.2.
- Удалить использование таких mounts и подождать добавления улучшенной возможности кеширования в werf v1.2.
- Включить используемые mounts в werf v1.2 с помощью конфигурационного файла
werf-giterminism.yaml
(не рекомендуется).
1. Использовать стратегию тегирования content-based
Стратегия тегирования content-based — это выбор по умолчанию и единственно доступный вариант, используемый в werf во время процесса деплоя.
- Необходимо удалить параметр
--tagging-strategy
командыwerf ci-env
. - Удалены опции
--tag-custom
,--tag-git-tag
,--tag-git-branch
, и--tag-by-stages-signature
. - В случае если требуется чтобы определённый docker tag для собранного образа существовал в container registry для использования вне werf, тогда допустимо использование параметров
--report-path
и--report-format
следующим образом:werf build/converge --report-path=images-report.json --repo REPO
;docker pull $(cat images-report.json | jq -r .Images.IMAGE_NAME_FROM_WERF_YAML.DockerImageName)
;docker tag $(cat images-report.json | jq -r .Images.IMAGE_NAME_FROM_WERF_YAML.DockerImageName) REPO:mytag
;docker push REPO:mytag
.
2. Использовать команду converge, заменить команду build-and-publish
- Команда
werf converge
должна быть использована вместоwerf deploy
сразу для сборки, публикации и деплоя приложения в kubernetes.- Команда поддерживает те же параметры, что и
werf deploy
.
- Команда поддерживает те же параметры, что и
- Команда
werf build-and-publish
была удалена.- Добавлена команда
werf build
, использование которой опционально.werf converge
самостоятельно собирает и публикует в container registry недостающие образы.werf build
же может быть использована на стадииprebuild
в CI/CD pipeline вместоwerf build-and-publish
.
- Добавлена команда
- Use
werf converge
command instead ofwerf deploy
to build and publish images, and deploy into kubernetes.- All params are the same as for
werf deploy
.
- All params are the same as for
werf build-and-publish
command has been removed, there is onlywerf build
command, usage of which is optional:werf converge
will build and publish needed images by itself, if not built already.- You may use
werf build
command in “prebuild” CI/CD pipeline stage instead ofwerf build-and-publish
command.
3. Изменить helm шаблоны
-
Вместо
werf_container_image
используется.Values.werf.image.IMAGE_NAME
:spec: template: spec: containers: - name: main image: {{ .Values.werf.image.myimage }}
- Полностью удалена шаблонная функция
werf_container_env
. - Необходимо использовать
.Values.werf.env
вместо.Values.global.env
. - Необходимо использовать
"werf.io/replicas-on-creation": "NUM"
вместо"werf.io/set-replicas-only-on-creation": "true"
. - Use
"werf.io/replicas-on-creation": "NUM"
annotation instead of"werf.io/set-replicas-only-on-creation": "true"
.- ВАЖНО.
"NUM"
должно быть указано строкой, а не как числоNUM
, иначе аннотация будет проигнорирована. - ВАЖНО. При использовании данной аннотации необходимо удалить явное определение поля
spec.replicas
, больше информации в changelog.
- ВАЖНО.
4. Использовать .helm/Chart.lock для сабчартов
- В соответствии с режимом гитерминизма werf не позволяет держать некоммитнутую директорию
.helm/charts/
. -
Для использования сабчартов необходимо определить dependencies в
.helm/Charts.yaml
следующим способом:# .helm/Chart.yaml apiVersion: v2 dependencies: - name: redis version: "12.7.4" repository: "https://charts.bitnami.com/bitnami"
- ВАЖНО. Следует обратить внимание на
apiVersion: v2
для использования описания зависимостей прямо в.helm/Chart.yaml
вместо.helm/dependencies.yaml
.
- ВАЖНО. Следует обратить внимание на
- Директория
.helm/charts/
добавляется в.gitignore
. - Далее следует запустить
werf helm dependency update .helm
для создания файла.helm/Chart.lock
и директории.helm/charts/
в локальной файловой системе. .helm/Chart.lock
надо коммитнуть в git репозиторий проекта.- werf автоматически скачает указанные сабчарты в кеш и загрузит файлы сабчартов во время команды
werf converge
(и других высокоуровневых командах, которые используют helm чарт). - Больше информации доступно в документации.
5. Использовать очистку на основе истории git
- Опцию
--git-history-based-cleanup-v1.2
необходимо удалить, теперь поведениеwerf cleanup
по умолчанию совпадает с поведением v1.1 с данной опцией. - Больше информации по изменению в changelog и в статье про cleanup.
6. Определить используемые переменные окружения в werf-giterminism.yaml
- ЗАМЕЧАНИЕ. Вообще говоря использование переменные окружения в
werf.yaml
не рекомендуется (за исключением редких случаев), больше информации в статье. -
Если в
werf.yaml
используются например переменные окруженияENV_VAR1
иENV_VAR2
, то необходимо добавить следующее описание вwerf-giterminism.yaml
:# werf-giterminism.yaml giterminismConfigVersion: 1 config: goTemplateRendering: allowEnvVariables: - ENV_VAR1 - ENV_VAR2
7. Скоректировать конфигурационный файл werf.yaml
- Относительные пути для включения дополнительных шаблонов меняются с {{ include “.werf/templates/1.tmpl” . }} на {{ include “templates/1.tmpl” . }}.
- Переименовать
fromImageArtifact
вfromArtifact
.- ЗАМЕЧАНИЕ. Не обязательно, но желательно заменить
artifact
иfromArtifact
наimage
иfromImage
в данном случае. Заметка про запрет использованияfromArtifact
в changelog.
- ЗАМЕЧАНИЕ. Не обязательно, но желательно заменить
8. Исправить определение нестандартной директории чарта .helm в werf.yaml
-
Вместо опции
--helm-chart-dir
используем директивуdeploy.helmChartDir
файлаwerf.yaml
следующим образом:configVersion: 1 deploy: helmChartDir: .helm2
-
Следует рассмотреть другой вариант расположения конфигурации для вашего проекта: werf v1.2 поддерживает несколько werf.yaml в едином git репозитории.
- Вместо переопределения нескольких разных
deploy.helmChartDir
вwerf.yaml
создаётся несколькоwerf.yaml
в разных директориях проекта - Каждая такая директория содержит свою директорию
.helm
соответственно. - werf запускаем из каждой директории.
- Все относительные пути указанные в
werf.yaml
будут рассчитаны относительно той директории, где лежитwerf.yaml
. - Абсолютные пути указанные в директиве
git.add
так и остаются абсолютными путями относительно корня git репозитория независимо от положенияwerf.yaml
внутри этого репозитория.
- Вместо переопределения нескольких разных
9. Мигрировать на helm 3
- werf v1.2 осуществляет автоматическую миграцию существующего релиза с helm 2 на helm 3.
- Релиз helm 2 должен иметь то же самое имя, как и вновь создаваемый релиз helm 3.
- Перед запуском процесса миграции werf проверит что текущие шаблоны из
.helm/templates
рендерятся и валидируются корректно и только после успешного рендеринга миграция будет начата. - ВАЖНО. Как только проект переехал на helm 3 не существует обратного пути на werf v1.1 и helm 2.