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

Инструкция описывает настройку автоматического механизма обновления всех сервисов, созданных из шаблона, при выпуске новой версии этого шаблона. Новая версия шаблона определяется по новому тегу, добавленному в Git-репозиторий шаблона.

Компоненты системы и их назначение

Для реализации автоматического обновления сервисов используются следующие компоненты платформы DDP:

• Ресурс:

  • В рамках инструкции используются два ресурса:

    • «Шаблоны» — хранит информацию о шаблонных репозиториях (URL и ID репозитория, последний тег версии).
    • «Сервисы» — хранит информацию о созданных сервисах (URL и ID репозитория, переменные шаблонизации, ветка по умолчанию).

    Названия могут отличаться, в зависимости от ваших настроек.

• Связь:

  • Устанавливает связь между шаблоном и созданными из него сервисами.

• Источник данных:

  • Синхронизирует информацию о шаблонных репозиториях из GitLab.
  • Обновляет список тегов для каждого шаблона.
  • Автоматически обновляет параметр «Последний тег» в сущностях ресурса «Шаблоны».

• Действие:

  • В данной настройке используются три действия:

    • создает новый проект в GitLab для размещения сервиса.
    • клонирует код из шаблонного репозитория в новый репозиторий сервиса с применением переменных шаблонизации.
    • создает Merge Request в репозитории сервиса с изменениями из новой версии шаблона.

    Названия могут отличаться, в зависимости от ваших настроек.

• Процесс:

  • В данной настройке процесс объединяет два действия:

    • Последовательно запускает создание проекта в GitLab, а затем создание репозитория из шаблона.
    • Обеспечивает интерфейс для пользователя при создании сервиса из шаблона.

• Автоматизация

  • Отслеживает изменения параметра «Последний тег» в сущностях ресурса «Шаблоны».
  • При обнаружении нового тега автоматически запускает действие «Обновление сервиса из шаблона» (название зависит от ваших настроек) для всех связанных сервисов.
  • Создает Merge Request в каждом репозитории сервиса с изменениями из новой версии шаблона.

Последовательность работы:

1. Источник данных периодически синхронизирует информацию о шаблонах из GitLab и обновляет параметр с идентификатором repository_last_tag (может отличаться в зависимости от ваших настроек) в сущностях ресурса «Шаблоны».
2. Автоматизация отслеживает изменения параметра с идентификатором repository_last_tag (может отличаться в зависимости от ваших настроек) через триггеры.
3. При обнаружении нового тега автоматизация запускает действие «Обновление сервиса из шаблона» (название может отличаться в зависимости от ваших настроек) для всех сервисов, связанных с обновленным шаблоном.
4. Действие создает Merge Request в репозитории каждого сервиса, включающий изменения из новой версии шаблона.

Таким образом, при добавлении нового тега в шаблонный репозиторий все связанные сервисы автоматически получают предложение обновиться через Merge Request.

Настройка компонентов

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

Будет описано:

1. Требуемые ресурсы в DDP и их параметры.
2. Требуемые связи между ресурсами.
3. Требуемые источники данных для получения информации о новых версиях шаблонов.
4. Требуемые действия для создания сервиса из шаблона.
5. Требуемый процесс для реализации последовательного запуска цепочки действий.
6. Требуемая автоматизация для реализации следующей функциональности:
   • автоматическая проверка платформой DDP наличия новой версии шаблона,
   • автоматическое создание в сервисах, созданных из шаблона, Merge Request с изменениями из новой версии.

Создание ресурсов и связи

Ресурсы — это элементы модели данных каталога DDP, которые определяют структуру хранения информации. Каждый ресурс может содержать параметры для хранения метаданных сущностей, а также связи с другими ресурсами для отображения зависимостей.

Ресурс «Шаблоны»

У вас должен быть создан ресурс для хранения информации о шаблонных репозиториях. В рамках данной инструкции он назван Шаблоны, однако вы можете использовать любое удобное для вас название. Если ресурса еще нет, создайте его.

Ресурс должен содержать следующие параметры для хранения данных о шаблонных репозиториях:

• Параметр «URL» типа URL — используется для хранения URL-адреса репозитория шаблона в GitLab. Этот параметр необходим для действий, которые работают с репозиторием шаблона.

• Параметр «ID репозитория» типа Number — хранит внутренний ID репозитория в GitLab. Используется для действий, которые требуют указания ID проекта GitLab.

• Параметр «Последний тег» типа String — содержит название последнего тега (версии) шаблона. Этот параметр используется автоматизацией для отслеживания появления новых версий шаблона. При каждом обновлении этого параметра источником данных автоматизация проверяет изменение и запускает обновление связанных сервисов.

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

Если параметры отсутствуют, откройте ресурс на редактирование и добавьте их на вкладке «Параметры» ресурса, нажав кнопку «Добавить параметр».

Ресурс «Сервисы»

У вас должен быть создан второй ресурс для хранения информации о созданных сервисах. В рамках инструкции он называется Сервисы, но вы можете выбрать любое удобное для вас название. Если ресурса еще нет, создайте его.

Ресурс должен содержать следующие параметры для хранения метаданных о созданных сервисах:

• Параметр «URL» типа URL — ссылка на репозиторий сервиса в GitLab. Используется действиями для работы с репозиторием сервиса.

• Параметр «ID репозитория» типа Number — внутренний ID репозитория в GitLab. Необходим для действий, которые требуют указания ID проекта GitLab.

• Параметр «Переменные использованные при шаблонизации» типа YAML — содержит переменные, которые были применены при клонировании кода из шаблона в сервис. Эти переменные необходимы при обновлении сервиса из шаблона, так как они должны быть применены повторно для корректного рендеринга новых изменений из шаблона.

• Параметр «Ветка по умолчанию» типа String — название основной ветки репозитория (например, main или master). Используется действием обновления сервиса для определения целевой ветки Merge Request.

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

Если параметры отсутствуют, откройте ресурс на редактирование добавьте их на вкладке «Параметры» ресурса, нажав кнопку «Добавить параметр».

Создание ресурса

Для создания ресурсов перейдите в раздел «Каталог». Создайте новый ресурс. Для этого в левом верхнем углу нажмите кнопку «Создать ресурс».

Откроется окно по созданию нового ресурса с различными вкладками.

Основная информация:

Заполните следующие поля на вкладке «Основная информация»:

• Название: [Укажите название ресурса].

• Владелец: [Укажите владельца].

• Команда владелец: [Укажите команду владелец].

Параметры:

Перейдите на вкладку «Параметры» и добавьте требуемые параметры ресурса. Для добавления нового параметра нажмите кнопку «Добавить параметр».

Пример требуемых параметров:

Шаблоны:

Сервисы:

Связь

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

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

Связь должна быть настроена следующим образом:

• Родительский ресурс: выбран ресурс, хранящий информацию о шаблонах.

• Дочерний ресурс: выбран ресурс, хранящий информацию о сервисах.

Создание связи

Для создания связи нажмите кнопку «Создать связь» в левом верхнем углу раздела «Каталог».

Откроется окно по созданию новой связи. Заполните данные согласно таблице ниже:

Источник данных

Источник данных — механизм DDP, который позволяет синхронизировать информацию из внешних инфраструктурных сервисов (например, GitLab) в каталог платформы. Источники данных периодически опрашивают внешние системы, получают актуальную информацию и обновляют соответствующие сущности в каталоге.

У вас должен быть настроен источник данных, который автоматически получает информацию об актуальном состоянии шаблонов из GitLab. Если источника данных еще нет, создайте его.

Проверьте следующие настройки:

Основная информация:

Ресурс: выбран ресурс «Шаблоны» (или соответствующий ресурс, если он назван иначе).

Backend:

На вкладке «Backend» проверьте подключение к GitLab, а именно, что происходит автоматическая синхронизация:

• Периодическая синхронизация: должна быть включена, для автоматического обновления информации о шаблонах при их изменении в GitLab.

• Периодичность запуска: должно быть указано расписание в формате CRON (например, 1 * * * * для запуска каждый час). Расписание определяет, как часто источник данных будет проверять наличие новых тегов в репозиториях шаблонов.

Параметры:

В параметрах должны быть заданы следующие ключи:

Подробнее о доступных параметрах.

Правила:

Правила обновления:

Настройте правила обновления параметров ресурса «Шаблоны» данными, полученными из GitLab:

• Параметр «URL»: необходимо хранить URL репозитория шаблона в GitLab. В качестве источника должен использоваться {{ .web_url }}.

• Параметр «ID репозитория»: необходимо хранить внутренний ID репозитория в GitLab. В качестве источника должен использоваться {{ .id }}.

• Параметр «Последний тег»: необходимо хранить последний тег git репозитория (в рамках данной инструкции используется как версия шаблона). Используется источник {{ ( index ( .ddp_repository_tags ) 0 ).name }}. Данное выражение получает последний тег, созданный в git-репозитории, беря первый элемент из массива тегов. Этот параметр критически важен для работы автоматизации, так как изменение его значения является триггером для обновления сервисов.

  • Примечание: данный способ получения версии шаблона является лишь примером, а не строгой необходимости. При необходимости способ получения тега можно настроить удобным для вас способом.

Примечание: идентификаторы источников берутся из спецификации Projects API GitLab.

Создание источника данных

Для создания источников данных перейдите в раздел «Самообслуживание» в пункт «Источники данных». В правом верхнем углу нажмите кнопку «Создать».

Откроется окно по созданию нового источника данных с различными вкладками.

Основная информация:

• Название: укажите название источника данных (например, Шаблоны сервисов).

• Ресурс: выберите ресурс, который содержит информацию о шаблонах.

• Владелец: назначьте владельца источника данных.

• Команда владелец: укажите команду, ответственную за источник данных.

Backend:

На вкладке «Backend» настройте подключение к GitLab:

• Backend: указывает встроенный тип источника данных. Необходим GitlabProjects для работы с проектами GitLab.

• Периодическая синхронизация: включите автоматический запуск синхронизации, для автоматического обновления информации о шаблонах при их изменении в GitLab.

• Периодичность запуска: укажите расписание в формате CRON (например, 1 * * * * для запуска каждый час). Расписание определяет, как часто источник данных будет проверять наличие новых тегов в репозиториях шаблонов.

• URL: укажите URL вашего экземпляра GitLab (например, https://gitlab.example.com).

Параметры:

Настройте параметры запроса к GitLab API:

Подробнее о доступных параметрах.

Правила:

На вкладке «Правила» настройте логику создания и обновления сущностей:

• Создание новых сущностей: включите создание новых сущностей. DDP автоматически будет создавать записи о новых шаблонах, если шаблонный репозиторий обнаружен в GitLab, но еще не существует в каталоге.

• Владелец создаваемых сущностей: назначьте владельца для новых сущностей.

• Команда владелец создаваемых сущностей: укажите команду-владельца для новых сущностей.

Правила создания:

Настройте правила для создания идентификатора и названия новой сущности в платформе:

• Идентификатор: идентификатор создаваемой сущности. Например, можно использовать выражение {{ replaceChar .path_with_namespace "/" "-" }}

  • Примечание: является лишь примером, а не строгой необходимостью. Данное выражение преобразует путь с пространством имен (.path_with_namespace из спецификации Projects API GitLab), заменяя слеши на дефисы для получения уникального ID.

• Название: название создаваемой сущность. Например, можно использовать выражение {{ .name }}

  • Примечание: является лишь примером, а не строгой необходимостью. Данное выражение использует название из GitLab (.name из спецификации Projects API GitLab)

Примечание: При необходимости вы можете задать свои собственные правила на основе Go Template.

Правила сопоставления:

Настройте правила сопоставления уже существующих сущностей при синхронизации:

• Идентификатор: идентификатор сущности, которую необходимо обновить. Например, можно использовать выражение {{ replaceChar .path_with_namespace "/" "-" }}

  • Примечание: является лишь примером, а не строгой необходимостью. Данное выражение преобразует путь с пространством имен (.path_with_namespace из спецификации Projects API GitLab), заменяя слеши на дефисы для получения уникального ID.

• Название: название сущности, которую необходимо обновить. Например, можно использовать выражение {{ .name }}

  • Примечание: является лишь примером, а не строгой необходимостью. Данное выражение использует название из GitLab (.name из спецификации Projects API GitLab).

Примечание: При необходимости вы можете задать свои собственные правила на основе Go Template. Если не планируется вручную создавать сущности ресурса, рекомендуется использовать одинаковые правила для сопоставления и создания.

Правила обновления:

Настройте правила обновления параметров ресурса «Шаблоны» данными, полученными из GitLab:

• Параметр «URL»: в качестве значения используется URL репозитория шаблона в GitLab. В качестве источника используйте {{ .web_url }}.

• Параметр «ID репозитория»: в качестве значения используется внутренний ID репозитория в GitLab. В качестве источника используйте {{ .id }}.

• Параметр «Последний тег»: в качестве значения используется тег git репозитория. Используйте источник {{ ( index ( .ddp_repository_tags ) 0 ).name }}. Данное выражение получает последний тег, созданный в git-репозитории, беря первый элемент из массива тегов. Этот параметр критически важен для работы автоматизации, так как изменение его значения является триггером для обновления сервисов.

  • Примечание: данный способ получения версии шаблона является лишь примером, а не строгой необходимости. При необходимости способ получения тега можно настроить удобным для вас способом.

Примечание: идентификаторы источников берутся из спецификации Projects API GitLab.

Авторизация:

На вкладке «Авторизация» настройте заголовки и учетные данные, необходимые для подключения к GitLab:

Настройте учетные данные:

• Идентификатор: token.

• Реквизиты: укажите реквизиты, которые содержат токен GitLab с необходимыми правами доступа к репозиториям. Токен должен иметь права на чтение проектов и информации о тегах в указанной группе GitLab.

Так же необходимо настроить заголовок:

• Ключ: Private-Token.

• Значение: {{ .credentials.token }} — используется значение, которое было настроено для учётных данных. Если в качестве идентификатора учётных данных используется не token, необходимо заменить token на заданное вами.

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

Создание действий

Действия — механизм DDP, который позволяет пользователям платформы взаимодействовать с внешними инфраструктурными сервисами через API. Действия могут создавать проекты в GitLab, создавать секреты в системах управления секретами, развертывать приложения и выполнять другие операции.

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

Действие «Создать проект в GitLab»

У вас должно быть создано действие, которое отвечает за инициализацию нового проекта в GitLab. Оно запускается первым при создании нового сервиса для создания проекта в GitLab, в который будет помещен созданный из шаблона сервис. Если действия еще нет, создайте его.

Проверьте, что действие содержит следующие настройки:

Основная информация:

• Ресурс: выбран ресурс, который содержит информацию о сервисах.

Обновление сущности:

На вкладке «Обновление сущности» активирована опция Обновление параметров сущности и настроены правила обновления, которые записывают ID, URL и ветку по умолчанию только что созданного проекта в сущность, для которой запускалось действие:

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

• Параметр «ID репозитория» используется источник {{ .response.id }} — сохраняет ID созданного проекта из ответа GitLab API в параметр сущности.

• Параметр «URL»: используется источник {{ .response.web_url }} — сохраняет URL проекта в GitLab созданного проекта в параметр сущности.

• Параметр «Ветка по умолчанию»: используется источник {{ .response.default_branch }} — сохраняет название ветки по умолчанию в параметр сущности.

Примечание: идентификаторы источников (id, web_url, default_branch) берутся из спецификации Projects API GitLab.

Действие «Создать репозиторий из шаблона»

У вас должно быть создано действие для клонирования кода из шаблонного репозитория в новый репозиторий сервиса с применением переменных шаблонизации. Это действие будет запускаться после создания проекта в GitLab и заполнять его кодом из шаблона. Если действия еще нет, создайте его.

Проверьте, что действие содержит следующие настройки:

Основная информация:

• Ресурс: выбран ресурс, который содержит информацию о сервисах (действие запускается для сущности сервиса, который нужно обновить).

Пользовательская форма:

Проверьте наличие следующих полей в пользовательской форме:

• Параметр «Идентификатор шаблонного репозитория» с идентификатором template_ddp_slug (или другим, если это необходимо) типа Entities — будет автоматически подставляться идентификатор сущности шаблона внутри DDP, из которого будет клонироваться код. В дополнительных настройках укажите: Ресурс: «Шаблоны» (или соответствующий ресурс), Связь: «Шаблоны-Сервисы» (или название вашей связи), Поле: «Идентификатор». Это позволяет выбрать нужный шаблон из связанных сущностей. Данный параметр можно сделать скрытым.

Обновление сущности:

На вкладке «Обновление сущности» активирована опция Обновление параметров сущности и настроено сохранение переменных, использованных при шаблонизации, обратно в сущность, для которой запускалось действие:

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

• Параметр «Переменные использованные при шаблонизации»: используйте источник {{ toYAML .response.values.merged }} — данное выражение сохраняет переменные в формате YAML. Эти переменные критически важны для будущего обновления сервиса из шаблона, так как они должны быть применены повторно. Данные получены в качестве ответа на успешное выполнение действия.

Активирована опция Создание связей сущностей, чтобы действие автоматически устанавливало связь между созданным сервисом и его шаблоном:

• Ресурс: выбран ресурс «Сервисы» (или соответствующий ресурс, если он назван иначе)

• Связь: выбрана связь «Шаблоны-Сервисы» (или название вашей связи, если оно отличается)

• Идентификатор родительской сущности: используйте {{ .property.template_ddp_slug }} — идентификатор шаблона из параметра действия

  • Важно: если идентификатор параметра не template_ddp_slug, замените на корректный

• Идентификатор дочерней сущности: оставьте пустым — будет использована текущая сущность, для которой запускается действие

Действие «Обновление сервиса из шаблона»

У вас должно быть создано действие, которое будет использоваться в автоматизации для создания нового Merge Request в репозиторий сервиса. Этот MR будет содержать изменения из новой версии (нового тега) связанного шаблона. Если действия еще нет, создайте его.

Проверьте, что действие содержит следующие настройки:

Основная информация:

• Ресурс: выбран ресурс, который содержит информацию о сервисах.

Пользовательская форма:

Проверьте наличие следующих полей в пользовательской форме:

• Параметр «Переменные используемые при шаблонизации" с идентификатором template_values (или другим, если это необходимо) типа String — он хранит переменные, которые были использованы при изначальной шаблонизации (хранятся в параметре сущности). Значение по умолчанию: {{ .entity.properties.template_values }} — использует сохраненные переменные из параметра сущности. Важно: если параметр называется иначе (например, template_vars), используйте соответствующий идентификатор.

• Параметр «Версия» с идентификатором version (или другим, если это необходимо) типа Entities — получает значение нового тега (версии) из сущности шаблона. В дополнительных настройках укажите: Ресурс: “Шаблоны” (или соответствующий ресурс, если он назван иначе), Связь: «Шаблоны-Сервисы» (или название вашей связи), Поле: “Параметр”, Параметр: «Последний тег» (или аналогичный).

• Параметр «Обновляемый репозиторий» с идентификатором target_project_id (или другим, если это необходимо) типа String — это ID репозитория сервиса в GitLab, в который создается MR. Значение по умолчанию: {{ .entity.properties.project_id }} — использует ID проекта из параметра сущности. Если идентификатор (project_id) параметра, который хранит внутренний ID проекта в GitLab в ресурсе называется иначе, используйте соответствующий идентификатор.

• Параметр «Шаблонный репозиторий» с идентификатором source_project_id (или другим, если это необходимо) типа Entities — это ID репозитория шаблона в GitLab. В дополнительных настройках укажите: Ресурс: «Шаблоны» (или соответствующий ресурс, если он назван иначе), Связь: «Шаблоны-Сервисы» (или название вашей связи), Поле: «Параметр», Параметр: «ID репозитория» (или аналогичный).

• Параметр «Ветка обновляемого репозитория» с идентификатором target_repo_branch (или другим, если это необходимо) типа String — это основная ветка репозитория сервиса (например, master или main), куда будет направлен MR. При необходимости можете указать любую другую. Значение по умолчанию: {{ .entity.properties.default_branch }} — использует ветку по умолчанию из параметра сущности. Если идентификатор параметра (default_branch) называется иначе, используйте соответствующий идентификатор.

Backend:

Тело запроса:

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

Тело запроса должно быть настроено примерно таким образом:

merge_request_spec:
  source_branch: update-to-{{ .version }}
  target_branch: {{ .target_repo_branch }}
  title: update-to-{{ .version }}
source_project_tag: {{ .version }}
source_project_id: "{{ .source_project_id }}"
target_project_id: "{{ .target_project_id }}"
values: {{ .template_values | nindent 4 }}

В теле запроса:

• source_branch — название ветки, содержащая изменения. В качестве примера, используется ветка с названием, включающим версию тега.
• target_branch — целевая ветка сервиса, куда будет направлен MR.
• title — заголовок MR с указанием версии.
• source_project_tag — тег версии шаблона, из которого берутся изменения.
• source_project_id и target_project_id — ID репозиториев шаблона и сервиса.
• values — переменные шаблонизации применяются повторно для корректного рендеринга изменений.

Подробнее о настройках встроенного бэкенда.

Создание действия

Для создания действия перейдите в раздел «Самообслуживание» пункт «Действия». Создайте новое действие. Для этого нажмите справа вверху кнопку «Создать». Откроется окно по созданию нового действия с различными вкладками.

Откроется окно по созданию нового действия с различными вкладками.

Вкладка «Основная информация»:

Заполните следующие поля на вкладке «Основная информация»:

• Название: [Укажите название действия].

• Ресурс: выберите ресурс «Сервисы» (или соответствующий ресурс, если он назван иначе).

• Владелец: [Укажите владельца].

• Команда владелец: [Укажите команду владелец].

Пользовательская форма:

На вкладке «Пользовательская форма» настройте поля для заполнения при запуске действия. Параметры, которые необходимо настроить зависят от действия, которое вы создаёте:

Действие «Создать проект в GitLab»:

• Параметр «Название» с идентификатором name (или иным при необходимости) типа String — это название нового проекта. Значение по умолчанию: {{ .entity.name }} — использует название сущности в DDP.

• Параметр «Путь» с идентификатором path (или иным при необходимости) типа String — это URL-путь до репозитория в GitLab. Значение по умолчанию: {{ .entity.slug }} — использует идентификатор сущности в DDP.

• Параметр «Группа репозиториев» с идентификатором group (или иным при необходимости) типа String — ID группы GitLab, где будет создан сервис. Значение по умолчанию: укажите ID группы в GitLab, в котором необходимо создать проект.

Действие «Создать репозиторий из шаблона»:

• Параметр «Идентификатор шаблонного репозитория» с идентификатором template_ddp_slug (или иным при необходимости) типа Entities — это идентификатор сущности шаблона внутри DDP, из которого будет клонироваться код. В дополнительных настройках укажите: Ресурс: «Шаблоны» (или соответствующий ресурс), Связь: «Шаблоны-Сервисы» (или название вашей связи), Поле: «Идентификатор». Это позволяет выбрать нужный шаблон из связанных сущностей.

• Параметр «URL сервисного репозитория» с идентификатором service_git_url (или иным при необходимости) типа URL — это URL репозитория, в который будет помещен отрендеренный шаблон. Значение по умолчанию: {{ .entity.properties.web_url }} — использует URL сущности сервиса из каталога. Если параметр URL в ресурсе называется иначе, используйте соответствующий идентификатор (например, {{ .entity.properties.service_url }}).

• Параметр «URL шаблонного репозитория» с идентификатором template_git_url (или иным при необходимости) типа Entities — это URL репозитория шаблона, который используется бэкендом для клонирования. В дополнительных настройках укажите: Ресурс: «Шаблоны» (или соответствующий ресурс), Связь: «Шаблоны-Сервисы» (или название вашей связи), Поле: «Параметр», Параметр: “URL” (или иной аналогичный, в зависимости от ваших настроек).

Дополнительные параметры зависят от вашего шаблона и должны быть настроены в соответствии с переменными, используемыми в шаблоне.

Действие «Обновление сервиса из шаблона»:

Необходимо настроить поля для сбора данных, которые нужны бэкенду для создания Merge Request. Эти данные будут автоматически заполняться из сущностей ресурса «Сервисы» или связанной с ним сущности из ресурса «Шаблоны»:

• Параметр «Переменные используемые при шаблонизации" с идентификатором template_values (или иным при необходимости) типа String — это переменные, которые были использованы при изначальной шаблонизации (хранятся в параметре сущности). Значение по умолчанию: {{ .entity.properties.template_values }} — использует сохраненные переменные из параметра сущности. Важно: если параметр называется иначе (например, template_vars), используйте соответствующий идентификатор

• Параметр «Версия» с идентификатором version (или иным при необходимости) типа Entities — получает значение нового тега (версии) из сущности шаблона. В дополнительных настройках укажите: Ресурс: «Шаблоны» (или соответствующий ресурс), Связь: «Шаблоны-Сервисы» (или название вашей связи), Поле: «Параметр», Параметр: «Последний тег» (или аналогичный).

• Параметр «Обновляемый репозиторий» с идентификатором target_project_id (или иным при необходимости) типа String — это внутренний ID репозитория сервиса в GitLab, в который создается MR. Значение по умолчанию: {{ .entity.properties.project_id }} — использует ID проекта из параметра сущности. Если параметр ID в ресурсе называется иначе, используйте соответствующий идентификатор

• Параметр «Шаблонный репозиторий» с идентификатором source_project_id (или иным при необходимости) типа Entities — это внутренний ID репозитория шаблона в GitLab. В дополнительных настройках укажите: Ресурс: «Шаблоны» (или соответствующий ресурс), Связь: «Шаблоны-Сервисы» (или название вашей связи), Поле: «Параметр», Параметр: “ID репозитория” (или аналогичный)

• Параметр «Ветка обновляемого репозитория» с идентификатором target_repo_branch (или иным при необходимости) типа String — основная ветка репозитория сервиса (например, master или main), куда будет направлен MR. Значение по умолчанию: {{ .entity.properties.default_branch }} — использует ветку по умолчанию из параметра сущности. Если идентификатор параметра называется иначе, используйте свой

Backend:

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

На вкладке «Backend» настройте логику выполнения действия. Логика зависит от настраиваемого действия.

Действие «Создать проект в GitLab»:

• Тип: выберите BuiltIn для использования встроенного бэкенда.

• Встроенный backend: выберите CreateGitlabProject для создания проекта в GitLab.

• URL: укажите URL вашего экземпляра GitLab (например, https://gitlab.example.com).

Тело запроса:

initialize_with_readme: false
name: '{{ .name }}'
namespace_id: '{{ .group }}'
path: '{{ .path }}'

Это тело запроса передает в GitLab API название проекта, ID группы и путь репозитория. Подробнее о настройках в документации.

Действие «Создать репозиторий из шаблона»:

• Тип: выберите BuiltIn для использования встроенного бэкенда.

• Встроенный backend: выберите CreateRepositoryFromTemplate для создания репозитория из шаблона.

• URL: укажите URL вашего экземпляра GitLab (например, https://gitlab.example.com).

Тело запроса:

sourceBranch: "master"
templateRepositoryUrl: "{{ .template_git_url }}"
targetRepositoryUrl: "{{ .service_git_url }}"
values:
  зависит от шаблона

В теле запроса:

• sourceBranch — ветка в репозитории шаблона, из которой будет клонироваться код (обычно master или main).

• templateRepositoryUrl — URL шаблонного репозитория из параметра действия.

• targetRepositoryUrl — URL целевого репозитория сервиса.

• values — блок должен содержать пары ключ-значение, которые будут использованы для замены переменных в файлах шаблона. Формат и состав этих переменных полностью зависит от того, как настроен ваш шаблон.

Подробнее о настройках в документации.

Действие «Обновление сервиса из шаблона»:

• Тип: выберите BuiltIn для использования встроенного бэкенда.

• Встроенный backend: выберите CreateGitlabMergeRequest для создания Merge Request в GitLab.

• URL: укажите URL вашего экземпляра GitLab (например, https://gitlab.example.com).

Тело запроса:

merge_request_spec:
  source_branch: update-to-{{ .version }}
  target_branch: {{ .target_repo_branch }}
  title: update-to-{{ .version }}
source_project_tag: {{ .version }}
source_project_id: "{{ .source_project_id }}"
target_project_id: "{{ .target_project_id }}"
values: {{ .template_values | nindent 4 }}

В теле запроса:

• source_branch — создается новая ветка с названием, включающим версию тега.

• target_branch — целевая ветка сервиса, куда будет направлен MR.

• title — заголовок MR с указанием версии.

• source_project_tag — тег версии шаблона, из которого берутся изменения.

• source_project_id и target_project_id — ID репозиториев шаблона и сервиса.

• values — переменные шаблонизации применяются повторно для корректного рендеринга изменений.

Подробнее о настройках в документации.

Обновление сущности:

Обновление параметров сущности:

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

Действие «Создать проект в GitLab»:

Используйте идентификаторы соответствующих параметров ресурса

• Параметр «ID репозитория»: используйте источник {{ .response.id }} — сохраняет ID созданного проекта из ответа GitLab API.

• Параметр «URL»: используйте источник {{ .response.web_url }} — сохраняет URL созданного проекта.

• Параметр «Ветка по умолчанию»: используйте источник {{ .response.default_branch }} — сохраняет название ветки по умолчанию.

Примечание: идентификаторы источников (id, .web_url, .default_branch) берутся из спецификации Projects API GitLab.

Действие «Создать репозиторий из шаблона»:

Используйте идентификатор соответствующего параметров ресурса.

• Параметр «Переменные использованные при шаблонизации»: используйте источник {{ toYAML .response.values.merged }} — данное выражение сохраняет переменные в формате YAML. Эти переменные критически важны для будущего обновления сервиса из шаблона, так как они должны быть применены повторно. Данные получены в качестве ответа на успешное выполнение действия.

Создание связей сущностей:

Для действия «Создать репозиторий из шаблона» так же должна быть активирована опция Создание связей сущностей, чтобы действие автоматически устанавливало связь между созданным сервисом и его шаблоном:

• Ресурс: выберите «Сервисы» (или соответствующий ресурс, если он назван иначе).

• Связь: выберите связь «Шаблоны-Сервисы» (или название вашей связи, если оно отличается).

• Идентификатор родительской сущности: используйте {{ .property.template_ddp_slug }} — идентификатор шаблона из параметра действия.

  Важно. Если идентификатор параметра не template_ddp_slug, замените на корректный.

• Идентификатор дочерней сущности: оставьте пустым — будет использована текущая сущность, для которой запускается действие.

Безопасность:

На вкладке «Безопасность» настройте учетные данные для выполнения действия. Настройки зависят от действия.

Действие «Создать проект в GitLab»:

• Идентификатор: token.

• Реквизиты: укажите реквизиты, которые содержат токен GitLab с необходимыми правами доступа для создания проектов в указанной группе.

Действие «Создать репозиторий из шаблона»:

• Идентификатор: password — реквизиты, которые содержат пароль (токен) GitLab с необходимыми правами доступа к репозиториям.

• Идентификатор: username — реквизиты, которые содержат GitLab username.

Действие «Обновление сервиса из шаблона»:

• Идентификатор: password — реквизиты, которые содержат пароль (токен) GitLab с необходимыми правами доступа к репозиториям.

• Идентификатор: username — реквизиты, которые содержат GitLab username.

Процесс

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

У вас должен быть создан процесс, который объединяет действия по созданию проекта в GitLab и создания сервиса из шаблона в единую последовательную автоматизированную цепочку. Процесс должен последовательно запускать создание проекта в GitLab, а затем создание репозитория из шаблона. Если процесса еще нет, создайте его.

Проверьте следующие настройки:

Основная информация:

Ресурс: выбран ресурс «Сервисы» (или соответствующий ресурс, если он назван иначе).

Конфигурация:

Названия действий могут отличаться в зависимости от ваших настроек.

Действия находится в следующей последовательности:

1. Start.
2. Создать проект в GitLab.
3. Создать репозиторий из шаблона.
4. End.

Создание процесса

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

Откроется окно по созданию нового процесса с различными вкладками.

Основная информация:

• Название: [Укажите название ресурса].

• Ресурс: выберите ресурс «Сервисы» (или соответствующий ресурс, если он назван иначе).

• Владелец: [Укажите владельца].

• Команда владелец: [Укажите команду владелец].

Конфигурация:

Названия задач и названия действий указываются в качестве примера. При необходимости укажите ваши.

На вкладке «Конфигурация» настройте шаги процесса и их порядок выполнения:

1. Добавьте элемент типа «Задача» с названием «Создать проект в GitLab» и выберите действие «Создать проект в GitLab» для запуска.
2. Добавьте элемент типа «Задача» с названием «Создать репозиторий из шаблона» и выберите действие «Создать репозиторий из шаблона» для запуска.
3. Добавьте элемент типа «Конец» для завершения процесса.

После добавления всех элементов настройте последовательность выполнения:

1. Start.
2. Создать проект в GitLab.
3. Создать репозиторий из шаблона.
4. End.

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

Автоматизации — механизм реагирования платформы на изменения спецификации сущностей. Автоматизации подписываются на события обновления сущностей ресурсов по определенным правилам (триггерам) и запускают выполнение действий, процессов или синхронизацию источников данных.

У вас должна быть настроена автоматизация, которая запускает действие по созданию Merge Request для обновления сервисов при появлении новой версии шаблона. Автоматизация отслеживает изменения параметра «Последний тег» (или аналогичный) в сущностях ресурса «Шаблоны» (или аналогичный) и при обнаружении нового тега автоматически запускает действие «Обновление сервиса из шаблона» (или аналогичный) для всех связанных сервисов. Если автоматизации еще нет, создайте её.

Проверьте следующие настройки:

Конфигурация:

Триггеры:

• Ресурс: выбран «Шаблоны» (или соответствующий ресурс, если он назван иначе)

• Условие: указано {{ ne .entity.properties.repository_last_tag "v1.0.0" }} (или аналогичное, если проерка у вас настроена иначе).

Примечание: данное условие срабатывает каждый раз, когда параметр с идентификатором repository_last_tag в сущности ресурса «Шаблоны» (или аналогичным) не равен указанному значению (v1.0.0). Условие будет проверяться только один раз при изменении параметра repository_last_tag. Важно: если параметр «Последний тег» (или аналогичный) имеет другой идентификатор (например, last_tag), используйте его в условии: {{ ne .entity.properties.last_tag "v1.0.0" }}

Execution:

• Executor: выбрано «Действия».

• Сущность: выбрано действие «Обновление сервиса из шаблона» (или соответствующее действие, если оно названо иначе).

Запускать execution для связанных ресурсов:

«Запускать execution для связанных ресурсов» — данный параметр включен и настроены связи ресурса:

• Ресурс: выбрано «Шаблоны» (или соответствующий ресурс).

• Связь: выбрана связь «Шаблоны-Сервисы» (или название вашей связи, если оно отличается).

Создание автоматизации

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

Основная информация:

• Название: [Укажите название автоматизации].

• Владелец: [Укажите владельца].

• Команда владелец: [Укажите команду владелец].

Конфигурация:

На вкладке «Конфигурация» настройте логику запуска автоматизации.

Триггеры:

Триггер определяет, когда автоматизация должна запускаться. Добавьте новый триггер:

• Ресурс: выберите «Шаблоны» (или соответствующий ресурс, если он назван иначе).

• Условие: укажите {{ ne .entity.properties.repository_last_tag "v1.0.0" }}. Важно: используется идентификатор параметра ресурса «Шаблоны» (или аналогичного), который хранит информацию о последнем теге git репозитория. Если идентификатор отличается, используйте корректный.

Данное условие срабатывает каждый раз, когда параметр repository_last_tag в сущности ресурса «Шаблоны» (или аналогичном) не равен указанному значению (v1.0.0). Условие будет проверяться только один раз при изменении параметра repository_last_tag. Важно: если параметр «Последний тег» имеет другой идентификатор (например, last_tag), используйте его в условии: {{ ne .entity.properties.last_tag "v1.0.0" }}.

Примечание: если планируется создание нескольких автоматизаций, каждая из которых должна реагировать на изменения параметров сущностей одного и того же ресурса, рекомендуется указывать условие в формате {{ and (ne .entity.properties.repository_last_tag "v1.0.0") (eq .entity.slug "example") }} для того, чтобы дополнительно фильтровать, какая из автоматизаций будет запускаться в каждом конкретном случае. Без добавления условия (eq .entity.slug "example") каждая из автоматизаций будет реагировать на изменения каждой сущности.

Execution:

Настройте выполнение действия:

• Executor: выберите «Действия».

• Сущность: выберите действие «Обновление сервиса из шаблона» (или соответствующее действие, если оно названо иначе).

Запускать execution для связанных ресурсов:

Автоматизация просматривает изменения в сущности ресурса «Шаблоны», но действие будет обновлять сущности ресурса «Сервисы», которые связаны с шаблоном, в котором произошло обновление параметра repository_last_tag.

Необходимо включить параметр Запускать execution для связанных ресурсов и настроить связи ресурса:

• Ресурс: выберите «Шаблоны» (или соответствующий ресурс).

• Связь: выберите связь «Шаблоны-Сервисы» (или название вашей связи, если оно отличается).

При обновлении тега в ресурсе «Шаблоны» (или соответствующий ресурс) система найдет все связанные с этим шаблоном сущности ресурса «Сервисы» (или соответствующий ресурс) и запустит для каждой из них действие «Обновление сервиса из шаблона» (или аналогичное), создавая Merge Request с изменениями из новой версии шаблона.

Создание сервиса

Настройка платформы для возможности создания сервисов на основе шаблона и последующим их автоматическим обновлением при выпуске новой версии шаблона завершена.

Для создания сервиса необходимо следующее:

1. Перейдите во вкладку «Каталог» в ресурс «Сервисы».
2. В правом верхнем углу нажмите кнопку «Создать».
3. В открывшемся окне во вкладке «Основная информация» заполните требуемые поля. Если настройки были произведены в соответствии с данной инструкцией, заполнение данных в других вкладках не требуются. Данные будут заполнены автоматически в дальнейшем.
4. Справа от появившейся записи о новом сервисе, нажмите на синюю кнопку с тремя вертикальными точками и выберите пункт «Запустить процесс».
5. В выпадающем списке выберите процесс Создание сервиса из шаблона.
6. При необходимости заполните переменные шаблона и запустите процесс.
7. При корректных настройках сервис будет создан. При наличии обновлений шаблоны для сервиса будут формироваться MR с изменениями. Проверить корректность создания можно перейдя в него и открыв вкладку «Запуски действий». Все действия должны быть в статусе Success.