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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Схема автоматического обновления:

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

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

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

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

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

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

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

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

«Ресурсы» — это элементы модели данных каталога 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). Используется действием обновления сервиса для определения целевой ветки запроса на слияние.

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

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

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

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

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

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

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

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

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

Вкладка «Параметры»

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

Пример параметров ресурса «Шаблоны»:

Пример параметров ресурса «Сервисы»:

Связь

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

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

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

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

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

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

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

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

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

Проверка источника данных

На вкладке «Основная информация» в поле «Ресурс» должен быть выбран ресурс «Шаблоны».

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

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

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

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

Подробнее о доступных параметрах — в разделе «GitlabProjects».

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

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

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

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

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

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

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

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

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

Заполните следующие поля:

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

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

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

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

Вкладка «Бэкенд»

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

• «Бэкенд»: выберите встроенный тип источника данных GitlabProjects для работы с проектами GitLab.

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

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

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

В параметрах бэкенда настройте параметры запроса к GitLab API:

Подробнее о доступных параметрах — в разделе «GitlabProjects».

Вкладка «Правила»

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

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

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

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

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

• «Идентификатор»: идентификатор создаваемой сущности. Например, можно использовать выражение {{ replaceChar .path_with_namespace "/" "-" }} — оно преобразует путь с неймспейсом, заменяя слеши на дефисы для получения уникального ID.
• «Название»: название создаваемой сущности. Например, можно использовать выражение {{ .name }} — оно использует название проекта из GitLab.

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

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

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

При необходимости вы можете задать свои собственные правила на основе 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 на заданное вами.

Подробнее о доступных заголовках — в разделах «GitlabProjects» и «Системная учётная запись».

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

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

Действие «Создать проект в 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, замените на корректный.

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

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

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

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

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

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

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

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

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

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

На вкладке «Конфигурация запроса» тело запроса должно быть настроено примерно таким образом:

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 — целевая ветка сервиса, куда будет направлен запрос на слияние.
• title — заголовок запроса на слияние с указанием версии.
• source_project_tag — тег версии шаблона, из которого берутся изменения.
• source_project_id и target_project_id — ID репозиториев шаблона и сервиса.
• values — переменные шаблонизации применяются повторно для корректного рендеринга изменений.

Подробнее о настройках встроенного бэкенда — в разделе «CreateGitlabMergeRequest».

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

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

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

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

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

• «Ресурс»: выберите ресурс «Сервисы».

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

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

Вкладка «Пользовательская форма»

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

Для действия «Создать проект в 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».

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

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

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

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

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

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

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

Вкладка «Конфигурация запроса»

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

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

• «Тип действия»: выберите встроенный тип действия (значение BuiltIn).
• «Встроенный тип действия»: выберите CreateGitlabProject для создания проекта в GitLab.
• «URL»: укажите URL вашего экземпляра GitLab (например, https://gitlab.example.com).

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

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

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

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

• «Тип действия»: выберите встроенный тип действия (значение BuiltIn).

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

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

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

sourceBranch: "master"
templateRepositoryUrl: "{{ .template_git_url }}"
targetRepositoryUrl: "{{ .service_git_url }}"
values:
  <KEY>: <VALUE>

Замените <KEY> и <VALUE> на имена и значения переменных вашего шаблона. Добавьте отдельную строку для каждой переменной.

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

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

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

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

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

Подробнее о настройках — в разделе «CreateRepositoryFromTemplate».

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

• «Тип действия»: выберите встроенный тип действия (значение BuiltIn).

• «Встроенный тип действия»: выберите CreateGitlabMergeRequest для создания запроса на слияние в 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 — целевая ветка сервиса, куда будет направлен запрос на слияние.

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

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

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

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

Подробнее о настройках — в разделе «CreateGitlabMergeRequest».

Вкладка «Обновление»

Для действий «Создать проект в 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.

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

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

Проверка автоматизации

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

• «Ресурс»: выбран «Шаблоны».

• «Условие»: указано {{ 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" }}.

Проверьте настройки выполнения:

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

• «Объект выполнения»: выбрано действие «Обновление сервиса из шаблона».

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

• «Ресурс»: выбрано «Шаблоны».

• «Связь»: выбрана связь «Шаблоны-Сервисы».

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

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

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

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

Заполните следующие поля:

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

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

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

Вкладка «Конфигурация»

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

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

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

• «Условие»: укажите {{ ne .entity.properties.repository_last_tag "v1.0.0" }}.

  Используется идентификатор параметра ресурса «Шаблоны», который хранит информацию о последнем теге git-репозитория. Если идентификатор отличается, используйте корректный.

Данное условие срабатывает каждый раз, когда параметр repository_last_tag в сущности ресурса «Шаблоны» не равен указанному значению (v1.0.0). Условие будет проверяться только один раз при изменении параметра repository_last_tag.

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

• «Тип выполнения»: выберите «Действия».

• «Объект выполнения»: выберите действие «Обновление сервиса из шаблона».

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

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

• «Связь»: выберите связь «Шаблоны-Сервисы».

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

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

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

Чтобы создать сервис:

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