Обновление из шаблона

Обновление из шаблона переносит изменения новой версии шаблона в репозиторий микросервиса, созданного из этого шаблона. Портал отрисовывает новую версию пакета со значениями параметров микросервиса, применяет изменения по стратегии обновления в отдельной ветке и открывает запрос на слияние. Изменения попадают в основную ветку после того, как владелец микросервиса примет запрос на слияние.

Перед началом работы

Для обновления из шаблона выполните следующие условия:

• подключён и синхронизирован реестр шаблонов;
• в правилах маппинга главной для шаблона привязан процесс действия «Обновить микросервис из шаблона»: «Микросервисы» → «Действия по шаблонам». Набор данных «Реестр шаблонов микросервисов» создаёт процесс «Обновить микросервис из шаблона», который можно привязать к любому шаблону;
• микросервис создан из шаблона: в репозитории есть lock-файл .ddp/template.lock.yaml, а у сущности микросервиса заполнены параметры привязки к шаблону.

Привязка микросервиса к шаблону

При создании микросервиса из шаблона портал записывает сведения о шаблоне в репозиторий и в каталог.

В репозиторий записывается lock-файл .ddp/template.lock.yaml:

templateId: go-service
templateVersion: 1.2.0
schemaVersion: 1
values:
  port: 8080
  database: postgres

Lock-файл содержит значения параметров, переданные при создании, без значений по умолчанию из схемы. По lock-файлу портал определяет текущую версию шаблона в репозитории и значения параметров для отрисовки новой версии. Не удаляйте и не изменяйте lock-файл вручную: без него репозиторий обновить нельзя.

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

Микросервис привязан к паре «шаблон и реестр»: обновления предлагаются только из версий шаблона того же реестра.

Политика обновления

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

• «Вручную» (manual) — обновление запускается только кнопкой «Обновить» в карточке микросервиса. Эта политика назначается при создании микросервиса;
• «Ревью автоматически» (review-auto) — портал сам запускает обновление после синхронизации, на которой появилась новая последняя версия, и открывает запрос на слияние.

Чтобы изменить политику, откройте сущность микросервиса в каталоге и измените параметр «Политика обновления шаблона».

Настройки обновления микросервиса

Стратегия и списки путей обновления задаются в манифесте пакета шаблона. Для отдельного микросервиса их можно переопределить параметрами сущности «Стратегия обновления шаблона», «Перезаписываемые пути обновления» и «Добавляемые пути обновления».

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

1. Параметры процесса обновления, если они заполнены при запуске.
2. Параметры сущности микросервиса, если они заполнены.
3. Поля update.strategy, update.overwrite и update.addIfMissing манифеста новой версии шаблона.
4. Стратегия selective, если стратегия нигде не задана.

Кнопка «Обновить» и автоматическое обновление передают выбранные настройки в контексте запуска процесса. Если процесс «Обновить микросервис из шаблона» из набора данных запускается без контекста, например из каталога, при пустом параметре «Стратегия обновления» используется selective.

Обнаружение новой версии

Новая версия шаблона обнаруживается при синхронизации реестра шаблонов. Если в результате синхронизации изменилась последняя версия шаблона, портал запускает автоматическое обновление подходящих микросервисов.

В карточке микросервиса на главной уведомление «Доступна версия {version}» отображается, если выполнены условия:

• у сущности микросервиса задан шаблон;
• у шаблона того же реестра есть последняя версия со статусом «доступна»;
• последняя версия выше версии шаблона микросервиса;
• у пользователя есть разрешение read:template-packs.

Уведомления о предварительных версиях, например 2.0.0-rc.1, видят только пользователи с разрешением read:template-registries. Переход на более раннюю версию не предлагается.

Ручное обновление

Ручное обновление запускает пользователь из карточки микросервиса на главной. Ручное обновление доступно при любой политике обновления.

Чтобы обновить микросервис:

1. Откройте раздел главной «Микросервисы» и выберите микросервис в таблице.
2. На вкладке «Справка» в блоке «Доступна версия {version}» нажмите «Обновить».
3. В окне «Запустить процесс» проверьте параметры и нажмите «Запустить».
4. Дождитесь завершения процесса и откройте запрос на слияние в GitLab. Ссылка на запрос на слияние сохраняется в хранилище процесса.

Кнопка «Обновить» недоступна в следующих случаях:

Автоматическое обновление

Автоматическое обновление запускает процесс обновления без участия пользователя после синхронизации, на которой у шаблона появилась новая последняя версия.

Портал запускает автоматическое обновление микросервиса, если выполнены все условия:

• в настройках реестра шаблонов задан «Пользователь автоматизации»;
• у микросервиса политика обновления «Ревью автоматически» (review-auto);
• новая последняя версия — стабильная, не предварительная;
• шаблон и реестр микросервиса совпадают с шаблоном и реестром новой версии;
• версия шаблона микросервиса в формате semver и ниже новой версии;
• репозиторий микросервиса находится в GitLab;
• к шаблону привязан процесс действия «Обновить микросервис из шаблона»;
• процесс обновления привязан к ресурсу микросервиса в поле «Ресурс» процесса;
• для микросервиса не выполняется процесс обновления;
• в репозитории нет открытого запроса на слияние из ветки с префиксом из настройки «Префикс ветки обновления».

После одной синхронизации запускается не больше обновлений, чем задано в настройке «Лимит очереди обновлений». Первыми запускаются обновления с наибольшим разрывом версий: сначала по major-версии, затем по minor и patch.

Автоматическое обновление также запускается после синхронизации кнопкой «Синхронизировать», в том числе при выключенном параметре «Включить синхронизацию». Отзыв, возврат и удаление версии на вкладке «Шаблоны» автоматическое обновление не запускают.

Пользователь автоматизации

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

Подготовьте пользователя автоматизации:

1. Создайте пользователя, например сервисного пользователя. Автоматический запуск процесса не проверяет разрешения пользователя на сущности микросервисов.
2. Заполните в профиле пользователя учётные данные GitLab — персональный токен и имя пользователя — для внешнего сервиса GitLab, в котором находятся репозитории микросервисов.
3. Выберите пользователя в поле «Пользователь автоматизации» на вкладке «Настройки» реестра шаблонов.

Учётные данные пользователя автоматизации используются также для проверки открытых запросов на слияние и для сверки версии шаблона.

Запросы на слияние при автоматическом обновлении создаются от имени пользователя автоматизации. Выдайте его учётной записи GitLab только права, необходимые для создания веток и запросов на слияние в репозиториях микросервисов.

Выполнение обновления

Процесс «Обновить микросервис из шаблона» из набора данных «Реестр шаблонов микросервисов» состоит из двух задач: «Обновление репозитория из шаблона» и «Создание код-ревью».

Задача «Обновление репозитория из шаблона» выполняет следующие шаги:

1. Определяет целевую версию: версию из параметра «Версия шаблона» или последнюю доступную версию шаблона из реестра микросервиса.
2. Клонирует основную ветку репозитория и читает lock-файл. Если версия в lock-файле отличается от версии в каталоге, портал исправляет версию в каталоге по lock-файлу.
3. Если версия в lock-файле не ниже целевой, завершает задачу без изменений; запрос на слияние не создаётся.
4. Отрисовывает новую версию пакета. Значения параметров: значения по умолчанию из схемы новой версии, поверх них — значения из lock-файла, поверх них — значения, переданные в процесс.
5. Создаёт ветку <префикс ветки обновления><версия>, например ddp/template-upgrade-1.3.0, от основной ветки.
6. Применяет изменения по стратегии обновления.
7. Записывает в lock-файл новую версию и значения параметров.
8. Создаёт коммит chore(template): upgrade <id> <старая версия> -> <новая версия> и отправляет ветку в GitLab.

Задача «Создание код-ревью» открывает запрос на слияние из ветки обновления:

• в ветку из параметра default_branch микросервиса, если он не задан — в main;
• с заголовком Upgrade <template_id> to <version>.

Если запрос на слияние из этой же ветки уже открыт, задача использует его. Если открыт запрос на слияние из другой ветки с тем же префиксом, задача завершается ошибкой review_already_open.

Портал не принимает запрос на слияние автоматически, не назначает ревьюеров и не отправляет уведомлений. Результат процесса отображается в панели «Мои активности» и в истории запусков процесса.

Стратегии обновления

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

Правила для всех стратегий:

• файлы вне области стратегии не изменяются;
• файлы не удаляются: файлы, удалённые или переименованные в новой версии шаблона, остаются в репозитории;
• в репозиторий не копируются template.yaml, values.yaml и .templateignore.

Списки путей — glob-шаблоны относительно корня репозитория, поддерживается синтаксис **, например deploy/**.

Если обязательный для стратегии список пуст, обновление завершается ошибкой invalid_upgrade_config.

Слияние

Стратегия merge сохраняет изменения, которые разработчики внесли в файлы из overwrite. Для каждого файла портал сравнивает три версии:

• базовую — файл, отрисованный из версии шаблона, указанной в lock-файле;
• текущую — файл в репозитории микросервиса;
• новую — файл, отрисованный из новой версии шаблона.

Если файла нет в репозитории, записывается новая версия файла. Переводы строк CRLF и перевод строки в конце файла сохраняются.

Любой конфликт слияния, в том числе различие бинарных файлов, прерывает обновление целиком: в репозиторий ничего не записывается, а процесс завершается ошибкой merge_conflict: merge conflict in files: <файлы>. Чтобы обновить микросервис с конфликтами, задайте для него другую стратегию, например selective, и перенесите изменения вручную в запрос на слияние.

Сверка версии после слияния

После принятия запроса на слияние портал обновляет версию шаблона микросервиса в каталоге. Сверка выполняется по расписанию из настройки «Интервал сверки версии шаблона».

Сверка выполняется, если в настройках реестра включён параметр «Включить синхронизацию» и задан «Пользователь автоматизации». Портал проверяет микросервисы, у которых версия шаблона в каталоге ниже последней доступной версии, читает lock-файл из ветки default_branch (или main) через API GitLab и повышает параметр «Версия шаблона», если версия в lock-файле выше.

Версия в каталоге только повышается. После сверки уведомление «Доступна версия {version}» в карточке микросервиса исчезает.

Если пользователь автоматизации не задан, версия в каталоге после принятия запроса на слияние не меняется до следующего запуска обновления: процесс обновления исправляет версию по lock-файлу.

Устранение ошибок

Ошибки обновления отображаются в журнале задачи процесса. Сообщение начинается с кода ошибки.

Чтобы повторить обновление, запустите процесс снова кнопкой «Обновить».