Чтобы мигрировать ваш проект с werf v1.1 на werf v1.2 следуйте приведенным ниже шагам.
ВНИМАНИЕ! Существуют такие конфигурации v1.1, которые используют директивы 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-тег для собранного образа существовал в 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 deploy
должна использоваться команда werf converge
. Она используется сразу для сборки, публикации и деплоя приложения в Kubernetes и поддерживает те же параметры, что и werf deploy
.
Изменения в командах (для справки):
- Команда
werf build-and-publish
удалена. - Добавлена команда
werf build
, использование которой опционально. werf converge
самостоятельно собирает и публикует в container registry недостающие образы.werf build
также может быть использована на стадииprebuild
в CI/CD pipeline вместоwerf build-and-publish
.
3. Используйте параметр --repo
вместо параметров --stages-storage
и --images-repo
Команда werf converge
хранит и собираемые образы и их стадии в container registry. Для указания хранилища, которое будет использоваться для хранения образов и стадий, теперь необходимо указать один параметр --repo
вместо двух используемых ранее ранее в v1.1 --stages-storage
и --images-repo
. Подробнее об этом параметре можно прочитать в changelog’е.
Аналогично и с переменными окружения, используемыми ранее: вместо WERF_STAGES_STORAGE
и WERF_IMAGES_REPO
теперь используется одна переменная WERF_REPO
.
4. Измените Helm-шаблоны
Вместо werf_container_image
используйте .Values.werf.image.IMAGE_NAME
:
spec:
template:
spec:
containers:
- name: main
image: {{ .Values.werf.image.myimage }}
ВАЖНО! Убедитесь, что используете
apiVersion: v2
! Это необходимо, чтобы разрешить описание зависимостей непосредственно в.helm/Chart.yaml
вместо.helm/dependencies.yaml
.
Изменения в Helm-шаблонах (для справки):
- Полностью удалена шаблонная функция
werf_container_env
. - Необходимо использовать
.Values.werf.env
вместо.Values.global.env
. - Необходимо использовать
.Values.werf.namespace
вместо.Values.global.namespace
. - Если в имени образа содержится дефис (
-
), то запись должна быть такого вида:image: '{{ index .Values.werf.image "IMAGE-NAME" }}'
. - Необходимо использовать
"werf.io/replicas-on-creation": "NUM"
вместо"werf.io/set-replicas-only-on-creation": "true"
.ВАЖНО!
"NUM"
должно быть указано строкой, а не как числоNUM
, иначе аннотация будет проигнорирована.ВАЖНО! При использовании данной аннотации необходимо удалить явное определение поля
spec.replicas
, больше информации в changelog.
5. Используйте .helm/Chart.lock
для сабчартов
В соответствии с режимом гитерминизма werf не позволяет держать некоммитнутую директорию .helm/charts/
. Для использования сабчартов необходимо определить dependencies
в .helm/Chart.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-чарт). Больше информации доступно в документации.
6. Используйте очистку на основе истории Git
Удалите опцию --git-history-based-cleanup-v1.2
— теперь поведение werf cleanup
по умолчанию совпадает с поведением v1.1 с данной опцией. Больше информации по изменению в changelog и в статье про cleanup.
7. Определите используемые переменные окружения в 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
8. Скоректируйте конфигурационный файл werf.yaml
- Замените относительные пути для включения дополнительных шаблонов с {{ include “.werf/templates/1.tmpl” . }} на {{ include “templates/1.tmpl” . }}.
- Переименуйте
fromImageArtifact
вfromArtifact
.ЗАМЕЧАНИЕ! Не обязательно, но желательно заменить
artifact
иfromArtifact
наimage
иfromImage
в данном случае. Заметка про запрет использованияfromArtifact
в changelog.
9. Исправьте определение нестандартной директории чарта .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
внутри этого репозитория.
10. Мигрируйте на Helm 3
werf v1.2 осуществляет автоматическую миграцию существующего релиза с Helm 2 на Helm 3.
Релиз Helm 2 должен иметь то же самое имя, как и вновь создаваемый релиз Helm 3.
Перед запуском процесса миграции werf проверит, что текущие шаблоны из .helm/templates
рендерятся и валидируются корректно, и только после успешного рендеринга миграция будет начата.
ВАЖНО! Как только проект переехал на Helm 3 – не существует обратного пути на werf v1.1 и Helm 2.