Миграция с v2 на v3

Начните со сводки изменений, затем проверьте разделы, относящиеся к вашей сборке, деплою и CI. Если нужен откат или параллельная работа с v2, прочитайте условия совместимости. Удалённые возможности требуют правок до обновления; переименование устаревших ключей можно отложить.

Изменения поведения по умолчанию

Если в v2 вы включали экспериментальные возможности, часть изменений уже действует в вашем окружении.

Эти изменения затрагивают существующие проекты даже без правок конфигурации:

Сборка и кеш

Деплой и бандлы

До первого werf plan проверьте скрытие чувствительных данных: прежняя аннотация больше не скрывает весь ресурс. Особенно важно для общедоступных логов CI.

CI и автоматизация

Отдельно — изменения контрактов CI, а не новые умолчания:

• При включённом --exit-code код 3 означает обновление только релиза — коды завершения plan.
• При переиспользовании образа JSON build report может содержать StagesSkipped: true без Stages — формат build report.
• JSON deploy report обозначает формат полем apiVersion вместо version — формат deploy report.

Совместимость с v2

Для параллельной работы и отката на v2 важны не только версии бинарей, но и общие конфигурация, секреты и registry:

• Конфигурация. После перехода на настройки v3 не рассчитывайте, что тот же werf.yaml будет работать в v2. Для отката сохраните совместимую с v2 ревизию конфигурации — см. изменения сборки.
• Секреты. Старые секреты читаются в v3, но новые записи v3 не читаются старым клиентом. Обновите всех читателей до первой перезаписи; замена бинаря обратно на v2 не вернёт прежний формат — см. зашифрованные секреты.
• Registry. Общий --repo означает общие образы: защитите образы для отката от очистки.

Сборка

После перехода на v3 ожидайте полную пересборку образов. Учтите её при планировании обновления.

Образы вместо artifacts

Для Stapel с artifact — обязательно. Замените artifact: builder на фрагмент:

image: builder
final: false

Остальные настройки образа сохраняются.

Для Stapel с disableGitAfterPatch — обязательно. Удалите директиву из werf.yaml: она больше не поддерживается, а неизвестный ключ — ошибка конфигурации. В v2 её предлагалось использовать, чтобы сохранить поведение artifact при замене artifact на image. В v3 эквивалентного переключателя нет. Чтобы ограничить, какие изменения запускают сборочные инструкции заново, используйте git.stageDependencies, но это не отключает обновление самих Git-файлов — подробнее.

Имена образов

Безымянные stapel-образы (image: ~) больше не поддерживаются — задайте каждому образу имя.

Имена теперь проверяются при загрузке конфигурации. Допустимы латинские буквы, цифры, _, ., - и +, а также сегменты через /. Каждый сегмент должен начинаться с буквы или цифры и заканчиваться буквой, цифрой или +. Имя modules/controller допустимо; пустое имя, пробелы, /api, api- и modules//controller вызывают ошибку конфигурации. Проверьте также имена, формируемые Go-шаблонами.

Единый from для ссылок на образы

Переименование можно отложить: fromImage, import.image и dependencies.image по-прежнему работают в v3 с предупреждением. При замене используйте только один из ключей: старый и новый одновременно вызывают ошибку.

Имя из werf.yaml, например base, обозначает внутренний образ; ссылка с тегом или digest, например alpine:3.20, — внешний. В dependencies вложенный блок imports по-прежнему передаёт информацию об образе, а не копирует файлы.

Переименование import.image не отменяет обязательного удаления import.stage — см. импорт файлов.

Внешний образ с явным тегом

Для внешних ссылок в базовом from или import.from — обязательно: укажите тег или digest. Например, замените from: ubuntu на from: ubuntu:latest, from: ubuntu:TAG или from: ubuntu@sha256:.... Внутренним именам образов из werf.yaml тег не нужен.

Билдеры и настройки образа

Для Dockerfile с Docker-бэкендом: legacy Docker builder больше не доступен. BuildKit уже использовался по умолчанию в v2, но DOCKER_BUILDKIT=0 или false позволял вернуться к старому builder. В v3 эта переменная не возвращает прежний режим: проверьте Dockerfile и окружение с BuildKit.

Для staged Dockerfile: WERF_STAGED_DOCKERFILE_VERSION=v1 больше не выбирает старую реализацию.

Для Stapel с ansible: — обязательно: Ansible-билдер удалён. Перепишите шаги ansible: с использованием Shell-билдера; переименования ключа недостаточно.

Для Stapel с docker: — обязательно: директива удалена. Перенесите настройки в imageSpec.config, преобразовав имена и форматы полей. Например, для фрагмента stapel-образа:

docker:
  WORKDIR: /app
  ENV:
    APP_ENV: production

imageSpec:
  config:
    workingDir: /app
    env:
      APP_ENV: production

Полный набор полей описан в разделе Изменение конфигурации образов.

Импорт файлов

Для образов Stapel с директивой import.

Кеш импорта теперь зависит от образа-источника, а не от контрольных сумм выбранных файлов, как было по умолчанию в v2. Изменение источника может вызвать пересборку образа-получателя, даже если копируемые файлы не изменились. includePaths/excludePaths по-прежнему выбирают файлы для копирования, но больше не изолируют кеш от остальных изменений источника. Если такие пересборки дороги, выделите импортируемый результат в отдельный небольшой образ.

Обязательно удалите import.stage. Импорт использует готовый образ-источник, а не выбранную промежуточную стадию. Если нужно промежуточное состояние, оформите его отдельным образом. before/after по-прежнему задают момент импорта в образе-получателе.

Например, фрагмент импорта из образа builder после удаления stage и необязательного переименования image в from:

import:
  - from: builder
    add: /out/message.txt
    to: /message.txt
    before: setup

Завершающий / в to: директив export/import теперь вызывает ошибку, кроме корневого пути to: /. Раньше werf убирал его с предупреждением, хотя пользователь мог ожидать копирование «внутрь каталога». Перед заменой to: /usr/sbin/ на to: /usr/sbin проверьте назначение:

• Если add — каталог, его содержимое сливается в to.
• Если add — файл, он копируется внутрь to, когда to — существующий каталог; иначе to — путь файла назначения. Чтобы результат не зависел от наличия родительского каталога, укажите полное имя файла, например to: /etc/app/config.yaml, и убедитесь, что по этому пути нет каталога.

Подробнее — правила пути назначения.

Зависимости стадий от Git

Для Stapel с Git mapping: git.stageDependencies определяет, какие изменения файлов Git запускают пересборку Shell-стадий.

В v3 отсутствие настройки и явный пустой список могут иметь разный смысл:

В частично заполненном блоке пропущенные стадии до последней явно объявленной получают [], а после неё — **/*. Порядок всегда install → beforeSetup → setup, независимо от порядка ключей YAML. Правило применяется отдельно для каждого git mapping. В v2 любая пропущенная стадия не зависела от файлов Git, независимо от позиции: новые **/* после последней объявленной стадии могут добавить пересборки.

Например, задан только beforeSetup:

git:
  - add: /
    to: /app
    stageDependencies:
      beforeSetup:
        - "src/**/*"

install получает [], beforeSetup — src/**/*, setup — **/*. Поэтому изменение файла вне src само по себе не запускает install или beforeSetup, но запускает setup, если у неё есть инструкции.

Чтобы сохранить отсутствие прямой Git-зависимости, задайте [] явно; чтобы стадия всегда учитывала все файлы mapping — ["**/*"]. Если задаёте маски, включите все файлы, влияющие на результат стадии.

[] отключает только прямую зависимость от файлов Git. Изменения предыдущих стадий, базового образа, команд и остальных входных данных по-прежнему могут вызвать пересборку.

Непустой stageDependencies для стадии без инструкций сборки теперь вызывает ошибку вместо предупреждения. Перенесите маски к стадии с соответствующими командами, добавьте недостающие инструкции или удалите лишнюю зависимость.

Подробнее — зависимость от изменений в Git-репозитории.

Проверка werf-giterminism.yaml

Исправьте неизвестные и опечатанные ключи в werf-giterminism.yaml: строгая проверка схемы больше не позволяет молча игнорировать их.

Какие образы собираются и выводятся

werf build и другие команды, запускающие сборку, теперь по умолчанию используют --final-images-only=true, как уже делали converge, render, export, plan, lint и bundle publish. «Сиротские» нефинальные образы, на которые не ссылается ни один финальный образ, больше не собираются по умолчанию.

werf config list также по умолчанию выводит только финальные образы; его устаревший алиас --images-only удалён.

Чтобы сохранить прежнее поведение:

werf build --final-images-only=false
werf config list --final-images-only=false

Buildah

Этот раздел нужен, если вы используете нативный Buildah-бэкенд. Он перешёл с CNI/slirp4netns на netavark/pasta: до обновления подготовьте окружение в зависимости от того, как вы запускаете werf.

Официальный образ werf

Обновите контейнерный образ werf до v3, а не только бинарь внутри него. netavark уже включён в образ; для запуска werf в этом контейнере отдельно устанавливать его на хост runner не нужно.

Официальные Ubuntu-образы werf теперь основаны на Ubuntu 24.04. Если вы создаёте на их основе собственные образы, пересоберите и проверьте их.

Для rootless-сборки с настройкой сети также проверьте наличие pasta внутри контейнера при условиях, описанных ниже: одного netavark недостаточно. Если pasta отсутствует, добавьте её в свой производный образ.

Собственная установка или образ

Если вы устанавливаете werf непосредственно на хост или используете собственный контейнерный образ, убедитесь, что зависимости доступны в среде выполнения werf:

Пути установки утилит и особенности совместного использования хранилища с Podman/Buildah — в разделе Сетевые утилиты.

Изменения сетевых настроек

Эти изменения действуют и внутри официального образа, и при других способах запуска.

Проверьте настройки сети. Для нестадийных Dockerfile-сборок на нативном Buildah теперь учитываются network: и --backend-network; раньше они молча игнорировались. Поддерживаются только default, host, none: bridge и имена Docker-сетей теперь вызывают ошибку.

Ограничения и совместимость:

• Для образов с staged: true настройка сети уровня образа по-прежнему игнорируется; действует только RUN --network= конкретной инструкции.
• В native-chroot Buildah принудительно использует хостовую сеть, поэтому network: none не обеспечивает изоляцию.
• Вернуть CNI нельзя. slirp4netns можно вернуть на отдельном хосте через CONTAINERS_CONF_OVERRIDE: default_rootless_network_cmd="slirp4netns" в секции [network].

Деплой

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

Чувствительные данные в diff

В v2 по умолчанию у Secret и любого ресурса с аннотацией werf.io/sensitive: "true" оставались видны только поля идентификации. В v3 автоматически скрываются только значения по путям data.* и stringData.*. Остальные поля, включая метаданные и имена ключей секрета, могут быть видны; скрытые значения заменяются информацией о длине и хеше.

Аннотация werf.io/sensitive: "true" больше не гарантирует скрытие всего произвольного ресурса. Если чувствительные данные находятся, например, в spec, укажите их JSONPath через werf.io/sensitive-paths, например "$.spec.token". Эта аннотация заменяет стандартный список путей, а не дополняет его: если нужно сохранить скрытие данных Secret, включите также $.data.* и $.stringData.*. Шифрование secret-values.yaml не задаёт правила скрытия полей отрендеренного ресурса.

Проверка ресурсов и values

Валидация Kubernetes-ресурсов по схемам включена по умолчанию. В v2 она требовала экспериментального флага. Ранее проходившие манифесты могут теперь отклоняться до применения. Исправьте ресурс или схему; для дополнительных схем используйте --resource-validation-extra-schema. Старые флаги --local-resource-validation, --resource-validation-kube-version и --resource-validation-schema удалены.

Если нужно исключение, используйте --resource-validation-skip; полное отключение — --no-resource-validation. Не отключайте проверку для всех ресурсов только ради одного неподдерживаемого типа.

Проверка values.schema.json уже существовала в v2, но обработка ошибок стала строже. Раньше ошибка о запрещённых служебных values могла превратить весь результат проверки в предупреждение, включая ошибки пользовательских values. Теперь werf повторяет проверку без служебных values и прекращает работу, если пользовательские values не соответствуют схеме. Исправьте values или схему; временное отключение — --no-values-schema-validation.

Автоматические патчи и null

patches.yaml основного чарта и его зависимостей теперь читается автоматически. Если файл с таким именем уже лежал в чарте для других целей, он может изменить манифесты или вызвать ошибку. Проверьте его до деплоя. Чтобы отключить автоматическое чтение, передайте --no-default-patches или задайте WERF_NO_DEFAULT_PATCHES=true.

Поля и элементы списков со значением null теперь удаляются рекурсивно. В v2 это требовало экспериментального флага. Отсутствующее поле и явный null не всегда равнозначны для Kubernetes и CRD, поэтому проверьте ресурсы, где null использовался намеренно. Переключателя для возврата прежнего поведения нет.

Нестроковые значения в metadata.annotations и metadata.labels теперь прерывают рендер с ошибкой decode resource. В v2 такие значения молча отбрасывались. Заключайте числа и булевы значения в кавычки в шаблонах, например example.com/replicas: "3". Ресурсы, уже сохранённые в релизе, не отклоняются: их некорректные записи отбрасываются с предупреждением.

Аннотации внешних зависимостей

Обязательно, если вы ожидаете ресурсы вне релиза: аннотации <name>.external-dependency.werf.io/resource и <name>.external-dependency.werf.io/namespace больше не поддерживаются. werf выводит предупреждение и не ждёт ресурс. Замените их на werf.io/deploy-dependency-<name>, указав kind, version, name и, для ресурса с группой, group.

Было — v2:

annotations:
  secret.external-dependency.werf.io/resource: secret/my-vault-secret
  secret.external-dependency.werf.io/namespace: vault

Стало — v3:

annotations:
  werf.io/deploy-dependency-secret: state=ready,kind=Secret,version=v1,name=my-vault-secret,namespace=vault,external=true

Подробнее — ожидание внешних ресурсов и зависимости ресурса.

Удаление и пересоздание ресурсов

Ресурсы теперь удаляются с распространением Background по умолчанию вместо Foreground. werf больше не ждёт исчезновения зависимых объектов удаляемого ресурса, например Pod’ов у Deployment, прежде чем продолжить. Если следующий шаг на это рассчитывает, задайте ресурсу werf.io/delete-propagation: Foreground или передайте --delete-propagation=Foreground / WERF_DELETE_PROPAGATION=Foreground.

Ресурс с helm.sh/resource-policy больше нельзя пересоздать. При изменении неизменяемого поля деплой завершается ошибкой cannot recreate the resource ... because its deletion is prohibited, а не удаляет и создаёт ресурс заново. Верните прежнее значение поля или снимите аннотацию на время этого деплоя.

Отслеживание готовности

Типы condition теперь сравниваются без учёта регистра. В v2 condition в CamelCase, например Ready или Available у пользовательского ресурса, не совпадал со встроенными правилами ready, и ресурс считался готовым сразу. Теперь werf ждёт, пока такой condition станет True. Если контроллер его никогда не выставляет, деплой завершится по таймауту: задайте ресурсу werf.io/track-termination-mode: NonBlocking или исправьте контроллер.

Рендер без кластера

Без доступа к кластеру werf render, werf lint и werf bundle render теперь считают версией Kubernetes 1.36.0 вместо 1.20.0. Соответственно меняется .Capabilities.KubeVersion, и шаблоны с ветвлением по нему могут отрендериться иначе. Чтобы закрепить прежнюю версию, передайте --kube-version.

Замена удалённых команд werf helm

Команды деплоя и просмотра релизов внутри werf helm удалены. Для проектов werf используйте отдельные команды:

Это замены рабочих сценариев, а не точные алиасы. converge, render и lint работают с проектом werf, а не с позиционными аргументами Helm RELEASE CHART. Проверьте --help новой команды, явно задайте нужные release и namespace и адаптируйте скрипты разбора вывода. Например, release get --print-values включает вычисленные values в структурированный вывод, а не повторяет вывод helm get values. Для работы с отдельными Helm-чартами используйте Helm CLI напрямую.

werf helm secret и команды работы с чартами, например werf helm dependency, сохраняются; вся группа werf helm не удалена.

Удаление релиза

werf dismiss теперь всегда использует новую реализацию удаления, которая в v2 включалась через WERF_EXPERIMENT_NEW_DISMISS. Выбор старой реализации и флаг --with-hooks удалены. Не переносите этот флаг в скрипты v3: проверьте сценарий удаления релиза и его hooks в тестовом окружении. Удаление namespace по-прежнему требует --with-namespace.

Values и переменные окружения

Старый ключ .Values.global.env может превратиться в пустое значение без ошибки. Для временной совместимости можно задать WERF_LEGACY_VALUES_GLOBAL_ENV=1.

Без замены HELM_DRIVER werf использует хранилище релизов по умолчанию, а не ранее указанное этой переменной.

Переменные путей Helm больше не читаются. HELM_CACHE_HOME, HELM_CONFIG_HOME и HELM_DATA_HOME игнорируются: список репозиториев чартов и кеш чартов ищутся через XDG_CONFIG_HOME и XDG_CACHE_HOME, по умолчанию ~/.config/helm и ~/.cache/helm в Linux. Эти переменные XDG задают родительские каталоги: например, при XDG_CONFIG_HOME=/custom/config werf читает /custom/config/helm/repositories.yaml, а не /custom/config/repositories.yaml. Чтобы использовать репозитории, добавленные в v2 при нестандартном HELM_CONFIG_HOME, скопируйте их repositories.yaml в новый каталог helm или добавьте репозитории заново. Одного присваивания XDG_CONFIG_HOME прежнего значения HELM_CONFIG_HOME недостаточно для сохранения пути.

Чарты и бандлы

В v3 .helmignore действует при чтении чарта. Исключённые файлы исчезают из сформированных манифестов и публикуемого бандла без предупреждения.

• Даже без .helmignore правила Helm по умолчанию исключают файлы и директории, начинающиеся с точки, непосредственно в templates/. Директории исключаются вместе с содержимым.
• ** теперь вызывает ошибку, хотя раньше не оказывал эффекта.
• Ведущий ! раньше не оказывал эффекта. Теперь он исключает всё, что не подошло под маску, как правило, оставляя чарт пустым. Не используйте его для отмены предыдущих исключений, как в .gitignore.

Правила для зависимых чартов зависят от способа подключения — см. Чарты и зависимости.

werf bundle publish теперь использует --helm-compatible-chart=true по умолчанию. Имя в Chart.yaml публикуемого бандла становится последним компонентом пути репозитория; меняются .Chart.Name и пути шаблонов. Чтобы сохранить имя из вашего Chart.yaml, передайте:

werf bundle publish --helm-compatible-chart=false

Зашифрованные секреты

Старый клиент не сможет прочитать секрет, записанный v3; возможности записать прежний формат нет. Соблюдайте порядок обновления:

1. Обновите все окружения, читающие секреты репозитория, до werf v3 или nelm v2: локальные машины, CI-задачи и задачи, применяющие сохранённые deploy plans.
2. Только после этого создавайте, редактируйте или ротируйте секреты. После перешифрования старый werf или nelm не должен работать с репозиторием.

На что обратить внимание:

• Старые зашифрованные скаляры остаются строками. Чтобы восстановить число, boolean, timestamp или другой тип, введите значение заново через werf helm secret values edit.
• Комментарии у зашифрованных значений сохраняются открытым текстом. Не записывайте в них секреты.

CI и скрипты

Credentials для registry

Если вы настраиваете CI через werf ci-env:

werf ci-env теперь автоматически использует непустой DOCKER_AUTH_CONFIG, если не передан --use-docker-auth-config и не задан WERF_USE_DOCKER_AUTH_CONFIG. В v2 требовалось явное включение.

При таком выборе Docker config создаётся из DOCKER_AUTH_CONFIG вместо копирования существующего config, а не объединяется с ним. Credentials и credential helpers из прежнего config могут перестать использоваться. Для прежнего выбора передайте --use-docker-auth-config=false или задайте WERF_USE_DOCKER_AUTH_CONFIG=false.

Коды завершения plan

При включённом --exit-code команды werf plan и werf bundle plan теперь всегда различают изменения ресурсов и обновление только релиза. В v2 расширенный набор кодов требовал экспериментального флага.

Обновите CI, если он допускает только 0 и 2. Код 3 — не ошибка, но и не основание автоматически пропускать применение. Без --exit-code успешный план не начинает возвращать 2 или 3.

Формат build report

Если ваши скрипты читают JSON build report:

При переиспользовании готового образа JSON build report теперь может содержать StagesSkipped: true без поля Stages. В v2 поле Stages присутствовало, хотя могло быть null. Парсер должен допускать отсутствие этого поля и не считать его ошибкой или признаком того, что образ не готов.

Формат deploy report

Если ваши скрипты читают JSON-отчёт, сохраняемый флагами --save-deploy-report, --save-rollback-report или --save-uninstall-report:

Изменился идентификатор формата: числовое поле "version": 3 заменено строковым "apiVersion": "v3", поля version больше нет. Обновите скрипты, читающие или проверяющие version: вместо него проверяйте apiVersion == "v3".

Удалённые флаги и режимы

Проверьте скрипты, которые передают старые параметры: удалённый флаг вызывает ошибку разбора, даже если раньше ничего не делал.

• Удалены --virtual-merge / WERF_VIRTUAL_MERGE, --skip-image-spec-stage / WERF_SKIP_IMAGE_SPEC_STAGE, --set-runtime-json и --show-verbose-diffs.
• --force-adoption удалён из werf render и werf bundle render, где он ни на что не влиял. В остальных командах деплоя флаг остаётся.
• Удалён Helm-режим через WERF_HELM3_MODE и запуск бинаря werf под именем helm; используйте поддерживаемые команды werf или отдельный Helm CLI.
• Позиционные имена образов у converge и plan теперь учитываются без WERF_CONVERGE_ENABLE_IMAGES_PARAMS. Проверьте, что случайные аргументы не стали выбирать образы; выбор образов сам по себе не ограничивает набор Kubernetes-ресурсов деплоя.

Очистка registry

Защита образов для отката

При общем --repo очистка v3 может удалить образы v2. Сохраните нужные для отката теги стадий в файле --keep-list, по одному на строку: на эти образы уже могут не ссылаться ресурсы Kubernetes.

Перед первой очисткой убедитесь, что образы для отката не попали в список удаления. Используйте те же репозитории, keep-list и доступ к Kubernetes, что и у периодического задания:

werf cleanup --repo registry.example.com/app --dry-run --keep-list keep-list.txt

Передайте используемые при сборке --final-repo и --meta-repo, если они настроены. Проверьте охват нужных кластеров и namespaces; --without-kube отключает защиту Kubernetes. Не используйте werf purge для удаления только образов v2: он удаляет образы проекта без политик сохранения cleanup. Подробнее — очистка container registry.