#TriggerTemplate

TriggerTemplate — это мощный компонент в Tekton Triggers, который определяет шаблон ресурсов, которые должны быть созданы при обнаружении события. Он выступает в роли действия в событийно-ориентированном пайплайне, точно указывая, какие ресурсы Kubernetes (обычно TaskRuns или PipelineRuns) должны быть созданы в ответ на события.

#Объяснение терминологии

#Зачем нужен TriggerTemplate

#Проблемы создания ресурсов на основе событий

В CI/CD системах, реагирующих на внешние события, возникают следующие сложности при создании ресурсов:

1. Динамическое создание ресурсов: Ресурсы, такие как пайплайны, должны создаваться с информацией, специфичной для каждого события.
2. Параметризация: Разные события требуют передачи различных параметров в пайплайны.
3. Повторное использование: Один и тот же шаблон создания ресурсов часто нужно использовать для разных событий.
4. Шаблонизация: Ручное создание ресурсов для каждого типа события подвержено ошибкам и плохо масштабируется.

Без TriggerTemplates решение этих задач потребовало бы:

• Пользовательских скриптов для генерации ресурсов Kubernetes для каждого события
• Сложной логики для подстановки параметров
• Дублирования определений ресурсов в разных обработчиках событий
• Ручной синхронизации между данными событий и созданием ресурсов

#Как TriggerTemplate решает эти задачи

TriggerTemplate предоставляет декларативный, нативный для Kubernetes способ:

1. Определять шаблоны ресурсов: Точно указывать, какие ресурсы должны создаваться при возникновении событий.
2. Параметризовать ресурсы: Использовать параметры, извлечённые из событий, для настройки ресурсов.
3. Обеспечивать согласованность: Создавать ресурсы с одинаковой структурой для похожих событий.
4. Разделять обязанности: Отделять обнаружение событий (EventListener) и извлечение данных (TriggerBinding) от создания ресурсов.
5. Обеспечивать повторное использование: Определять шаблоны один раз и использовать их в разных триггерах.

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

#Преимущества

• Декларативное определение: Определение создаваемых ресурсов с помощью нативного YAML Kubernetes
• Параметризация: Динамическая настройка ресурсов с помощью данных событий
• Повторное использование: Создание шаблонов один раз и использование их в нескольких триггерах
• Разделение обязанностей: Чёткое разделение между обнаружением событий, извлечением данных и созданием ресурсов
• Значения по умолчанию: Возможность задавать запасные значения для параметров, которые могут отсутствовать в событиях
• Динамическое именование: Генерация ресурсов с уникальными именами для избежания конфликтов
• Несколько ресурсов: Создание нескольких ресурсов из одного события
• Валидация ресурсов: Проверка ресурсов во время выполнения перед созданием

#Применимые сценарии

TriggerTemplates необходимы в следующих случаях:

1. Автоматизированные CI/CD пайплайны: Автоматическое создание запусков пайплайнов при пушах кода или открытии pull request.
2. Мульти-средовые деплои: Использование одного шаблона с разными параметрами для деплоя в разные среды.
3. Событийно-ориентированные рабочие процессы: Создание ресурсов в ответ на события внешних систем, например обновления задач или оповещения мониторинга.
4. Динамическое создание ресурсов: Генерация ресурсов с параметрами, специфичными для каждого события, например ID коммита или имя ветки.
5. Параметризованное тестирование: Создание тестовых пайплайнов с разными параметрами в зависимости от типа события.
6. Шаблоны конфигурации во время выполнения: Предоставление стандартизированных конфигураций времени выполнения (параметры, рабочие пространства, контексты безопасности и т.д.) для многократного запуска пайплайнов. Пользователи могут выбирать подходящие шаблоны через UI фронтенда для быстрого создания экземпляров PipelineRun, соответствующих требованиям сценария.

#Ограничения и лимитации

• Параметры в TriggerTemplates могут быть только строковыми значениями
• JSON-объекты требуют аккуратного обращения при использовании в параметрах
• Валидация ресурсов происходит во время выполнения, а не при создании
• Для ресурсов, не относящихся к Tekton, может потребоваться расширение прав сервисного аккаунта по умолчанию
• Встроенные ресурсы должны быть включены в PipelineRun или TaskRun, которые их используют
• Имена параметров с числовыми префиксами требуют особой обработки

#Принципы

#Структура TriggerTemplate

TriggerTemplate состоит из двух основных разделов:

1. Определение параметров: Объявляет параметры, которые могут использоваться в шаблонах ресурсов
2. Шаблоны ресурсов: Определяет ресурсы Kubernetes, которые должны быть созданы

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: example-template
spec:
  params:
    - name: param1
      description: Описание параметра 1
      default: default-value  # Необязательное значение по умолчанию
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: example-pipeline-run-
      spec:
        pipelineRef:
          name: example-pipeline
        params:
          - name: pipeline-param
            value: $(tt.params.param1)

#Обработка параметров

Параметры в TriggerTemplates подчиняются следующим принципам:

1. Объявление: Параметры должны быть объявлены в разделе params с указанием имени и, опционально, описания и значения по умолчанию.

2. Обращение: Параметры используются в шаблонах ресурсов с помощью синтаксиса $(tt.params.имя-параметра).

3. Значения по умолчанию: Если параметр не передан через TriggerBinding, используется значение по умолчанию, если оно указано.

4. Строковые значения: Все значения параметров рассматриваются как строки, даже если они представляют числа или JSON-объекты.

5. Специальные символы: Параметры с числовыми префиксами или специальными символами могут требовать кавычек в шаблонах ресурсов.

#Создание шаблонов ресурсов

При обнаружении и обработке события:

1. EventListener получает событие
2. Interceptors обрабатывают и фильтруют событие (если настроены)
3. TriggerBindings извлекают данные из события
4. TriggerTemplate получает извлечённые параметры
5. Происходит подстановка параметров в шаблонах ресурсов
6. Создаются ресурсы Kubernetes с подставленными значениями

Каждому созданному ресурсу добавляются метки для отслеживания происхождения:

• tekton.dev/eventlistener: <EventListenerName>
• tekton.dev/triggers-eventid: <EventID>

#Шаблоны конфигурации времени выполнения

1. Конвенции по меткам

• triggertemplate.triggers.tekton.dev/usage: runtime-config

  Должна быть установлена в runtime-config для идентификации назначения шаблона.

• tekton.dev/pipeline: <pipeline-name>

  Связывает шаблон с конкретным пайплайном.

• triggertemplate.triggers.tekton.dev/runtime-config-default: "true"

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

2. Конвенции по шаблонам ресурсов

• В spec.resourcetemplates может быть определён только один ресурс PipelineRun.
• Обязательно должен быть указан pipelineRef для ссылки на целевой пайплайн.
• Поддерживаются все поля конфигурации времени выполнения PipelineRun, такие как params, workspaces, podTemplate и др.

#Примеры конфигураций

#Базовый шаблон CI пайплайна

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: ci-pipeline-template
spec:
  params:
    - name: git-revision
      description: SHA коммита git
    - name: git-repo-url
      description: URL репозитория git
    - name: git-repo-name
      description: Имя репозитория git
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: $(tt.params.git-repo-name)-ci-
      spec:
        pipelineRef:
          name: ci-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
          - name: repo-url
            value: $(tt.params.git-repo-url)
        workspaces:
          - name: source
            emptyDir: {}

#Шаблон деплоя в несколько сред

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: deploy-template
spec:
  params:
    - name: environment
      description: Среда деплоя
      default: development
    - name: image-tag
      description: Тег образа для деплоя
    - name: app-name
      description: Имя приложения
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: deploy-$(tt.params.app-name)-$(tt.params.environment)-
      spec:
        pipelineRef:
          name: deployment-pipeline
        params:
          - name: target-environment
            value: $(tt.params.environment)
          - name: image-tag
            value: $(tt.params.image-tag)
          - name: application
            value: $(tt.params.app-name)

#Шаблон с несколькими ресурсами

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: multi-resource-template
spec:
  params:
    - name: git-revision
      description: SHA коммита git
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: build-pipeline-
      spec:
        pipelineRef:
          name: build-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: test-pipeline-
      spec:
        pipelineRef:
          name: test-pipeline
        params:
          - name: revision
            value: $(tt.params.git-revision)

#Шаблон конфигурации времени выполнения

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: deploy-pipeline-staging-config
  labels:
    triggertemplate.triggers.tekton.dev/usage: runtime-config
    tekton.dev/pipeline: deploy-pipeline
    triggertemplate.triggers.tekton.dev/runtime-config-default: true
spec:
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: deploy-pipeline-staging-
      spec:
        pipelineRef:
          name: deploy-pipeline
        params:
          - name: environment
            value: "staging"
          - name: replicas
            value: "2"
        workspaces:
          - name: config
            configMap:
              name: staging-config

#Важные пояснения по параметрам, связанным с TriggerTemplate

#Подстановка параметров

Подстановка параметров — это основной механизм, делающий TriggerTemplates динамичными и переиспользуемыми.

#Применимые сценарии

• Вставка SHA коммитов в PipelineRuns
• Использование URL репозиториев и имён веток в параметрах пайплайнов
• Передача метаданных событий в пайплайны
• Кастомизация имён ресурсов с учётом информации о событии

#Ограничения и лимитации

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

#Принципы/пояснения по параметрам

Синтаксис подстановки параметров: $(tt.params.имя-параметра), где имя-параметра — имя параметра, объявленного в разделе params TriggerTemplate.

Пример:

params:
  - name: git-revision
    description: SHA коммита git
resourcetemplates:
  - apiVersion: tekton.dev/v1
    kind: PipelineRun
    spec:
      params:
        - name: revision
          value: $(tt.params.git-revision)

#Работа с JSON

При работе с JSON-данными в TriggerTemplates необходимы особые меры.

#Применимые сценарии

• Передача сложных структур данных в пайплайны
• Работа с полезной нагрузкой вебхуков, содержащих вложенный JSON
• Создание ресурсов, требующих JSON-конфигурации

#Ограничения и лимитации

• JSON-объекты должны обрабатываться как строки
• Экранирование кавычек может быть сложным
• Для устаревших шаблонов могут потребоваться специальные аннотации

#Принципы/пояснения по параметрам

Для работы с JSON-объектами:

1. Не заключайте JSON-параметры в кавычки при использовании в шаблонах ресурсов
2. Для устаревших шаблонов, требующих экранированных кавычек, добавьте аннотацию:

   metadata:
     annotations:
       triggers.tekton.dev/old-escape-quotes: "true"

#Справочные материалы

• Tekton Triggers Documentation
• TriggerTemplate Official Documentation
• Tekton Pipelines Documentation
• Kubernetes Resource Management