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

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

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

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

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

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

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

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

• Связь:

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

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

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

• Действие — механизм DDP, который позволяет пользователям платформы взаимодействовать с внешними инфраструктурными сервисами через API. Действия могут создавать проекты в 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.

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

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

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

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

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

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

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

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

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

Параметры:

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

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

Шаблоны:

Сервисы:

Связь

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

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

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

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

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

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

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

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

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

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

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

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

Бэкенд:

На вкладке «Бэкенд» проверьте подключение к 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 }} — сохраняет название ветки по умолчанию в параметр сущности.

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

У вас должно быть создано действие для клонирования кода из шаблонного репозитория в новый репозиторий сервиса с применением переменных шаблонизации. Это действие будет запускаться после создания проекта в 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) называется иначе, используйте соответствующий идентификатор.

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

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

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

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 — переменные шаблонизации применяются повторно для корректного рендеринга изменений.

Подробнее о настройках встроенного бэкенда — в разделе «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» (или иной аналогичный, в зависимости от ваших настроек).

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

Необходимо настроить поля для сбора данных, которые нужны бэкенду для создания 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 }} — использует ветку по умолчанию из параметра сущности. Если идентификатор параметра называется иначе, используйте свой.

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

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

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

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

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

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:
  зависит от шаблона

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

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

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

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

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

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

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

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

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

Подробнее о настройках — в разделе «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.

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

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

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

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

Триггеры:

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

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

Выполнение:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Триггеры:

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

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

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

Выполнение:

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

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

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

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

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

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

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

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

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

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

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

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

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